@atlashub/smartstack-cli 3.37.0 → 3.38.0

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

@@ -0,0 +1,127 @@
+# Resume and Recovery Logic
+
+> **Reference for:** step-00-init.md sections 4 (Resume Mode) and 4a (Auto-Recovery)
+> **Purpose:** Handle resumption of interrupted loops and auto-recovery from BA artifacts
+
+---
+
+## Resume Mode
+
+If `{resume_mode} = true` (user passed `-r` flag):
+
+```javascript
+// Check PRD exists
+if (!fileExists('.ralph/prd.json')) {
+  console.error('ERROR: -r flag set but .ralph/prd.json not found');
+  STOP;
+}
+
+const prd = readJSON('.ralph/prd.json');
+
+// Detect format
+let resumeValid = false;
+if (prd.$version === '3.0.0') {
+  // v3 unified — native format
+  resumeValid = true;
+  console.log('Resume: v3.0.0 unified PRD');
+} else if (prd.$version === '2.0.0') {
+  // v2 legacy — OK to resume
+  resumeValid = true;
+  console.log('Resume: v2.0.0 legacy PRD');
+} else if (prd.project && prd.requirements && !prd.$version) {
+  // FORMAT A deprecated — warn but transform
+  console.warn('⚠ DEPRECATED: FORMAT A prd.json detected during resume');
+  console.warn('Re-run `ss derive-prd` to generate v3 format');
+  // NOTE: Transformation happens in step-01, not here
+  resumeValid = true;
+} else {
+  console.error('ERROR: .ralph/prd.json format not recognized');
+  STOP;
+}
+
+if (resumeValid) {
+  // Check branch consistency
+  const branch = prd.metadata?.branch || 'unknown';
+  const currentBranch = getCurrentBranch();
+  if (branch !== currentBranch) {
+    console.warn(`⚠ Branch mismatch: PRD from ${branch}, currently on ${currentBranch}`);
+    console.warn('Continuing anyway — verify this is intentional');
+  }
+
+  // Restore state
+  {current_iteration} = prd.config?.current_iteration || 1;
+  {completion_promise} = prd.config?.completion_promise || null;
+  {max_iterations} = prd.config?.max_iterations || 50;
+
+  // Restore multi-module state if present
+  if (fileExists('.ralph/modules-queue.json')) {
+    {modules_queue} = readJSON('.ralph/modules-queue.json');
+    {current_module} = {modules_queue}.modules[{modules_queue}.currentIndex]?.code;
+    console.log(`Multi-module resume: ${{current_module}} (${{modules_queue}.currentIndex + 1}/${{modules_queue}.totalModules})`);
+  }
+
+  console.log(`Resuming from iteration ${{current_iteration}}`);
+  // Continue to step-01
+}
+```
+
+---
+
+## Auto-Recovery: BA Artifacts Without PRD
+
+If no PRD files exist (neither `.ralph/prd-*.json` nor `.ralph/prd.json`):
+
+```javascript
+const masterFeature = findFile('docs/business/**/business-analyse/**/feature.json');
+
+if (!masterFeature) {
+  // No BA artifacts found — start fresh
+  console.log('No existing PRD or BA artifacts — starting new loop');
+  return;
+}
+
+const master = readJSON(masterFeature);
+const handoffStatus = master.status || master.handoff?.status || null;
+
+if (handoffStatus === 'handed-off') {
+  // BA handoff completed — auto-derive PRDs
+  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}`);
+
+  if (result.exitCode !== 0) {
+    console.error('ss derive-prd failed — cannot auto-recover');
+    STOP;
+  }
+
+  const newPrds = glob('.ralph/prd-*.json');
+  if (newPrds.length === 0) {
+    console.error('ss derive-prd did not create any PRD files');
+    STOP;
+  }
+
+  console.log(`Auto-recovered ${newPrds.length} PRD file(s): ${newPrds.map(f => f.split('/').pop()).join(', ')}`);
+  // Continue to detect multi-module (section 4b)
+} else {
+  // BA handoff NOT complete
+  console.warn(`⚠ BA handoff status: "${handoffStatus}" (expected "handed-off")`);
+  console.warn('Cannot auto-recover PRD files without complete handoff');
+  console.warn('Run /business-analyse to complete the handoff, then retry /ralph-loop');
+  STOP;
+}
+```
+
+---
+
+## State After Recovery
+
+After resume or auto-recovery:
+
+```javascript
+// If PRD now exists (either resumed or recovered):
+// - Continue to section 4b (Detect Multi-Module)
+// - Initialize modules-queue.json if 2+ PRD files found
+// - Set {modules_queue} and {current_module} appropriately
+// - Proceed to step-01 to load tasks
+```

package/templates/skills/ralph-loop/references/module-transition.md

@@ -0,0 +1,151 @@
+# Module Transition Logic
+
+> **Reference for:** step-04-check.md section 3b
+> **Trigger:** Multi-module mode + current module complete
+> **Purpose:** Advance to next module in queue OR finish if all done
+
+---
+
+## When Module Transition Occurs
+
+```javascript
+const queuePath = '.ralph/modules-queue.json';
+if (fileExists(queuePath)) {
+  const queue = readJSON(queuePath);
+  const currentModule = queue.modules[queue.currentIndex];
+
+  // MODULE COMPLETENESS CHECK
+  const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
+  const expected = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
+  const missing = expected.filter(c => !completedCats.has(c));
+
+  if (missing.length > 0) {
+    console.log(`Module ${currentModule.code}: missing categories ${missing.join(', ')} — continuing loop`);
+    // Fall through to compact loop (section 5)
+    return;
+  }
+
+  // All categories present — module is complete
+  // Continue below...
+}
+```
+
+---
+
+## Advance to Next Module
+
+```javascript
+if (missing.length === 0) {
+  // Mark current module done
+  currentModule.status = 'completed';
+  queue.completedModules++;
+  const nextIndex = queue.currentIndex + 1;
+
+  if (nextIndex < queue.totalModules) {
+    // More modules to process
+    queue.currentIndex = nextIndex;
+    queue.modules[nextIndex].status = 'in-progress';
+    writeJSON(queuePath, queue);
+
+    // Signal module transition to step-01
+    writeJSON('.ralph/module-changed.json', {
+      fromModule: currentModule.code,
+      toModule: queue.modules[nextIndex].code,
+      timestamp: new Date().toISOString()
+    });
+
+    // Mark current PRD as complete
+    prd.status = 'completed';
+    writeJSON('.ralph/prd.json', prd);
+
+    // Load next module's PRD
+    const nextPrd = readJSON(queue.modules[nextIndex].prdFile);
+    nextPrd.config.current_iteration = 1;
+    nextPrd.config.max_iterations = prd.config.max_iterations;
+    writeJSON('.ralph/prd.json', nextPrd);
+
+    console.log(`MODULE COMPLETE: ${currentModule.code} → NEXT: ${queue.modules[nextIndex].code}`);
+
+    // Return to step-01 to load next module's tasks
+    // (step-01 will detect module-changed.json and load next PRD)
+    return GO_TO_STEP_01;
+  }
+
+  // ALL MODULES COMPLETE
+  // Continue to section 3c (completion output) → step-05
+}
+```
+
+---
+
+## Check: All Modules Complete
+
+```javascript
+if (nextIndex >= queue.totalModules) {
+  // No more modules
+  writeJSON(queuePath, queue);
+  console.log(`ALL ${queue.totalModules} MODULES COMPLETE`);
+
+  // Fall through to step 3c (completion output) → step-05
+}
+```
+
+---
+
+## Step-01 Module Detection
+
+When returning to step-01 after module transition:
+
+```javascript
+// In step-01, section 0:
+const moduleChangePath = '.ralph/module-changed.json';
+if (fileExists(moduleChangePath)) {
+  const transition = readJSON(moduleChangePath);
+  console.log(`Module transition: ${transition.fromModule} → ${transition.toModule}`);
+  deleteFile(moduleChangePath);
+
+  // This is an exception to "Read Once" rule — PRD has changed
+  // PROCEED with loading the new module's tasks
+}
+```
+
+---
+
+## State Transitions
+
+```
+[Phase A: Module 1]
+├─ step-01: Load tasks from prd-module1.json
+├─ step-02: Delegate to /apex
+├─ step-03: Commit PRD state
+├─ step-04: Check completion
+│  └─ If all categories complete:
+│     ├─ Write module-changed.json
+│     ├─ Write next PRD to .ralph/prd.json
+│     └─ Return to step-01 ✓
+│
+└─ [Phase B: Module 2]
+   ├─ step-01: Detect module-changed.json, load next PRD
+   ├─ step-02: Delegate to /apex
+   ├─ ... (repeat for module 2)
+   │
+   └─ [Module 2 complete]
+      ├─ Mark module 2 done in modules-queue.json
+      ├─ Check if more modules
+      │  ├─ If yes: Transition to module 3 (goto Phase C)
+      │  └─ If no: Fall through to step-05 ✓
+      │
+      └─ [Phase N: Final Module]
+         ├─ ... (repeat)
+         └─ ALL MODULES COMPLETE → step-05
+```
+
+---
+
+## Rules
+
+- **Module completeness check runs EVERY iteration:** Not just once
+- **Exception to "Read Once":** When transitioning modules, step-01 re-reads the new PRD
+- **Atomic module advancement:** Only transition when all required categories are complete
+- **Max iterations applies globally:** Not per-module
+- **State persistence:** modules-queue.json tracks progress across modules

package/templates/skills/ralph-loop/references/multi-module-queue.md

@@ -0,0 +1,171 @@
+# Multi-Module Queue Initialization
+
+> **Reference for:** step-01-task.md section 0
+> **Purpose:** Initialize multi-module state when 2+ PRD files detected
+> **Output:** modules-queue.json with module list and current index
+
+---
+
+## Detection
+
+```javascript
+const prdFiles = glob('.ralph/prd-*.json');
+const PRD_COUNT = prdFiles.length;
+
+if (PRD_COUNT === 0) {
+  {modules_queue} = null;
+  {current_module} = null;
+  return;  // Single module mode or no PRDs
+}
+
+if (PRD_COUNT === 1) {
+  // Single module
+  {modules_queue} = null;
+  {current_module} = null;
+  return;  // Use standard mode
+}
+
+// PRD_COUNT > 1 → Multi-module detected
+```
+
+---
+
+## Module Queue Construction
+
+```javascript
+const modules = [];
+
+// Step 1: Get module order from master feature.json
+const masterFeature = findFile('docs/business/**/business-analyse/**/feature.json');
+let moduleOrder = [];
+
+if (masterFeature) {
+  const master = readJSON(masterFeature);
+  moduleOrder = master.metadata?.workflow?.moduleOrder || [];
+}
+
+// Step 2: Build queue in order
+for (const mod of moduleOrder) {
+  const prdFile = `.ralph/prd-${mod.code}.json`;
+  if (fileExists(prdFile)) {
+    modules.push({
+      code: mod.code,
+      prdFile: prdFile,
+      status: 'pending'
+    });
+  }
+}
+
+// Step 3: Fallback to alphabetical if no order from feature.json
+if (modules.length === 0) {
+  for (const file of prdFiles) {
+    const code = file.match(/prd-(.+)\.json$/)[1];
+    modules.push({
+      code: code,
+      prdFile: `.ralph/${file}`,
+      status: 'pending'
+    });
+  }
+  modules.sort((a, b) => a.code.localeCompare(b.code));
+}
+
+// Step 4: Initialize first module as in-progress
+if (modules.length > 0) {
+  modules[0].status = 'in-progress';
+}
+```
+
+---
+
+## Queue State Structure
+
+```javascript
+const queue = {
+  modules: modules,              // Array of {code, prdFile, status}
+  currentIndex: 0,               // Index of currently executing module
+  totalModules: modules.length,  // Total count
+  completedModules: 0            // Count of completed modules
+};
+
+writeJSON('.ralph/modules-queue.json', queue);
+
+{modules_queue} = queue;
+{current_module} = modules[0].code;
+
+console.log(`Multi-module: ${modules.length} modules → ${modules.map(m => m.code).join(' → ')}`);
+```
+
+---
+
+## Module Transition (Next Iteration)
+
+When calling step-01 after a module completes:
+
+```javascript
+// Check for module transition marker
+if (fileExists('.ralph/module-changed.json')) {
+  const transition = readJSON('.ralph/module-changed.json');
+  console.log(`Module transition: ${transition.fromModule} → ${transition.toModule}`);
+  deleteFile('.ralph/module-changed.json');
+
+  // PROCEED — this is an exception to the "Read Once" rule
+  // Continue to load the new module's PRD
+}
+```
+
+---
+
+## PRD Loading for Current Module
+
+```javascript
+const queuePath = '.ralph/modules-queue.json';
+if (fileExists(queuePath)) {
+  const queue = readJSON(queuePath);
+  const currentModule = queue.modules[queue.currentIndex];
+
+  const currentPrd = readJSON('.ralph/prd.json');
+  if (currentPrd.metadata?.moduleCode !== currentModule.code) {
+    // Module has changed — load new PRD
+    const modulePrd = readJSON(currentModule.prdFile);
+
+    // v3 FAST PATH
+    if (modulePrd.$version === '3.0.0') {
+      modulePrd.status = 'in_progress';
+      modulePrd.feature = `${modulePrd.project?.module || currentModule.code} (${modulePrd.project?.application || 'app'})`;
+      modulePrd.created = modulePrd.created || new Date().toISOString();
+      modulePrd.updated_at = new Date().toISOString();
+      modulePrd.config = modulePrd.config || {
+        max_iterations: {max_iterations},
+        completion_promise: "{completion_promise}",
+        current_iteration: 1
+      };
+      modulePrd.metadata.branch = modulePrd.metadata.branch || getCurrentBranch();
+      modulePrd.metadata.project_path = modulePrd.metadata.project_path || process.cwd();
+      modulePrd.metadata.mcp_servers = modulePrd.metadata.mcp_servers || { smartstack: true, context7: true };
+      modulePrd.history = modulePrd.history || [];
+      writeJSON('.ralph/prd.json', modulePrd);
+    }
+    // LEGACY: FORMAT A
+    else if (modulePrd.project && modulePrd.requirements && !modulePrd.$version) {
+      console.warn('⚠ DEPRECATED: FORMAT A prd.json detected. Re-run `ss derive-prd` to generate v3 format.');
+      writeJSON('.ralph/prd.json', transformPrdJsonToRalphV2(modulePrd, currentModule.code));
+    }
+    // v2 legacy
+    else {
+      writeJSON('.ralph/prd.json', modulePrd);
+    }
+  }
+
+  {current_module} = currentModule.code;
+}
+```
+
+---
+
+## Single Module Mode
+
+If PRD_COUNT === 0 or 1:
+- {modules_queue} = null
+- {current_module} = null
+- Skip multi-module logic
+- Use standard single-module compact loop

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

@@ -0,0 +1,246 @@
+# Parallel Execution Mode (Agent Teams)
+
+> **Reference for:** step-02-execute.md section 3a
+> **Trigger:** `-p` flag OR `{parallel_mode} == true`
+> **Applicability:** Multi-module only (2+ modules)
+
+---
+
+## Overview
+
+When Ralph detects 2+ modules with `-p` flag:
+
+1. **Phase 0 (Ralph sequential):** Generate ALL entities from ALL modules + ONE migration
+2. **Phase 1-N (Teams parallel):** Spawn teammates per application/module for services/controllers/frontend/tests
+3. **Cleanup:** Collect results, validate, TeamDelete
+
+---
+
+## Phase 0: Foundation (Sequential)
+
+### 1. Collect All Entities
+
+```javascript
+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(', ')}`);
+```
+
+### 2. Invoke /apex --foundation
+
+Ralph invokes `/apex --foundation -d .ralph/prd.json` which:
+- Generates ALL entity classes
+- Generates ALL EF configurations
+- Registers ALL DbSets in DbContext
+- Creates ONE migration with all entities
+- **SKIPS** services/controllers/frontend/tests
+
+```bash
+/apex --foundation -d .ralph/prd.json
+```
+
+### 3. Commit Foundation
+
+```bash
+git add .
+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>"
+```
+
+Result: ModelSnapshot contains all entities. Database ready for application layers.
+
+---
+
+## Phase 1-N: Parallel Teams
+
+### 1. Determine Teammate Granularity
+
+Applications can have 1-N modules. Teammate strategy:
+
+```javascript
+const teammates = [];
+const applicationsMap = {}; // { appName: [module1, module2, ...] }
+
+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(', ')}`);
+}
+```
+
+### 2. Create Team
+
+```javascript
+TeamCreate({
+  team_name: `smartstack-${kebabCase(prd.project.name || 'project')}`,
+  description: `Parallel development for ${teammates.length} modules`
+});
+```
+
+### 3. Spawn Teammates
+
+```javascript
+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):
+All entity classes, EF configurations, and migrations are complete.
+The ModelSnapshot is complete and the database is ready.
+DO NOT attempt to create entities or migrations.
+
+YOUR TASK:
+For each module in ${teammate.modules}, 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 in Phase 0)
+- Create migrations (ModelSnapshot already complete)
+- Modify DbContext (already done in Phase 0)
+
+EXECUTE:
+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:
+{
+  "type": "completion",
+  "teammate": "${teammate.name}",
+  "status": "complete" | "failed",
+  "modules": ${JSON.stringify(teammate.modules)},
+  "summary": "Brief summary of what was generated"
+}
+    `
+  });
+}
+```
+
+### 4. Wait for Teammates
+
+Ralph waits for all teammates to send completion messages:
+
+```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);
+  }
+}
+
+if (teamMateResults.length < teammates.length) {
+  console.error(`TIMEOUT: ${teammates.length - teamMateResults.length} teammates did not complete`);
+  // Set status to 'partial'
+}
+```
+
+### 5. Collect & Validate Results
+
+```javascript
+const completedTeammates = teamMateResults.filter(r => r.status === 'complete').length;
+const failedTeammates = teamMateResults.filter(r => r.status === 'failed').length;
+
+console.log(`Phase 1-N completed:`);
+console.log(`  ✅ ${completedTeammates} teammates succeeded`);
+console.log(`  ❌ ${failedTeammates} teammates failed`);
+console.log(`  ⏱ ${teammates.length - teamMateResults.length} teammates did not respond`);
+```
+
+### 6. Cleanup Team
+
+```javascript
+TeamDelete();
+```
+
+---
+
+## Fallback (Non-Parallel)
+
+If `-p` flag NOT set OR only 1 module detected:
+
+- **Single module:** Ralph executes compact loop normally (no teams)
+- **Multi-module (no -p):** Check for dependency graph in feature.json
+  - If graph exists → Classic Agent Teams (layered approach)
+  - If no graph → Sequential compact loop per module
+
+---
+
+## Rules
+
+- **Phase 0 is sequential:** Ralph must complete foundation first
+- **Phase 1-N is parallel:** Teammates execute in parallel
+- **No entity duplication:** Phase 1 teammates skip domain/infrastructure
+- **Timeout:** 1 hour per phase (configurable)
+- **Partial success OK:** If some teammates fail, continue validation