@atlashub/smartstack-cli 2.7.1 → 2.7.3

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

@@ -16,6 +16,173 @@ Load the current task from prd.json or create initial task breakdown with catego
 
 ## EXECUTION SEQUENCE:
 
+### 0. Multi-Module Queue Check
+
+**Before any other logic, check for modules-queue.json:**
+
+```javascript
+const queuePath = '.ralph/modules-queue.json';
+const hasQueue = fileExists(queuePath);
+
+if (hasQueue) {
+  const queue = readJSON(queuePath);
+  const currentModule = queue.modules[queue.currentIndex];
+
+  console.log(`Module ${queue.currentIndex + 1}/${queue.totalModules}: ${currentModule.code}`);
+
+  // Copy current module's prd file to prd.json (overwrite)
+  const modulePrd = readJSON(currentModule.prdFile);
+
+  // Transform PrdJson format to Ralph v2 if needed
+  if (modulePrd.project && modulePrd.requirements && !modulePrd.$version) {
+    // This is a PrdJson format from ss derive-prd → transform to Ralph v2
+    const transformedPrd = transformPrdJsonToRalphV2(modulePrd, currentModule.code);
+    writeJSON('.ralph/prd.json', transformedPrd);
+  } else {
+    // Already Ralph v2 format
+    writeJSON('.ralph/prd.json', modulePrd);
+  }
+
+  console.log(`Loaded PRD for module: ${currentModule.code}`);
+}
+```
+
+**PrdJson → Ralph v2 transformation:**
+
+The PrdJson format (from `ss derive-prd`) has this structure:
+```
+{ version, source, project, requirements: { useCases[], functionalRequirements[] },
+  businessRules[], architecture: { entities[], apiEndpoints[], sections[] },
+  implementation: { filesToCreate: { domain[], application[], infrastructure[], api[], frontend[], tests[] } },
+  seedData }
+```
+
+```javascript
+function transformPrdJsonToRalphV2(prdJson, moduleCode) {
+  const tasks = [];
+  let taskId = 1;
+
+  // Layer processing order (SmartStack convention)
+  const layerOrder = [
+    { key: "domain",         category: "domain" },
+    { key: "infrastructure", category: "infrastructure" },
+    { key: "application",    category: "application" },
+    { key: "api",            category: "api" },
+    { key: "frontend",       category: "frontend" },
+    { key: "seedData",       category: "infrastructure" },
+    { key: "tests",          category: "test" }
+  ];
+
+  const filesToCreate = prdJson.implementation?.filesToCreate || {};
+
+  // 1. Generate tasks from implementation.filesToCreate (primary source)
+  const lastIdByCategory = {};
+
+  for (const layer of layerOrder) {
+    const files = filesToCreate[layer.key] || [];
+    for (const fileSpec of files) {
+      const depIds = [];
+      // Depend on last task in same category (sequential within layer)
+      if (lastIdByCategory[layer.category]) {
+        depIds.push(lastIdByCategory[layer.category]);
+      }
+      // Cross-layer: api depends on last application task, frontend depends on last api task
+      if (layer.category === "api" && lastIdByCategory["application"]) {
+        depIds.push(lastIdByCategory["application"]);
+      }
+      if (layer.category === "frontend" && lastIdByCategory["api"]) {
+        depIds.push(lastIdByCategory["api"]);
+      }
+      if (layer.category === "test" && lastIdByCategory["api"]) {
+        depIds.push(lastIdByCategory["api"]);
+      }
+
+      // Build acceptance criteria from linked FRs and UCs
+      const linkedFRs = (fileSpec.linkedFRs || [])
+        .map(frId => {
+          const fr = prdJson.requirements?.functionalRequirements?.find(f => f.id === frId);
+          return fr ? fr.statement : frId;
+        });
+      const criteria = linkedFRs.length > 0
+        ? `Implements: ${linkedFRs.join("; ")}`
+        : `File ${fileSpec.path} created and compiles correctly`;
+
+      tasks.push({
+        id: taskId,
+        description: fileSpec.description
+          ? `[${layer.category}] ${fileSpec.description} → ${fileSpec.path}`
+          : `[${layer.category}] Create ${fileSpec.type}: ${fileSpec.path}`,
+        status: "pending",
+        category: layer.category,
+        dependencies: [...new Set(depIds)],
+        acceptance_criteria: criteria,
+        started_at: null,
+        completed_at: null,
+        iteration: null,
+        commit_hash: null,
+        files_changed: { created: [fileSpec.path], modified: [] },
+        validation: null,
+        error: null,
+        module: moduleCode
+      });
+
+      lastIdByCategory[layer.category] = taskId;
+      taskId++;
+    }
+  }
+
+  // 2. Add a final validation task
+  tasks.push({
+    id: taskId,
+    description: `[validation] Build, test, and MCP validate module ${moduleCode}`,
+    status: "pending",
+    category: "validation",
+    dependencies: Object.values(lastIdByCategory),
+    acceptance_criteria: "dotnet build succeeds, dotnet test passes, MCP validate_conventions clean",
+    started_at: null,
+    completed_at: null,
+    iteration: null,
+    commit_hash: null,
+    files_changed: { created: [], modified: [] },
+    validation: null,
+    error: null,
+    module: moduleCode
+  });
+
+  return {
+    $version: "2.0.0",
+    feature: `${prdJson.project?.module || moduleCode} (${prdJson.project?.application || "app"})`,
+    status: "in_progress",
+    created: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    metadata: {
+      cli_version: "unknown",
+      branch: getCurrentBranch(),
+      project_path: process.cwd(),
+      mcp_servers: { smartstack: true, context7: true },
+      module: moduleCode
+    },
+    config: {
+      max_iterations: {max_iterations},
+      completion_promise: "{completion_promise}",
+      current_iteration: 1
+    },
+    source: {
+      type: "ba-handoff",
+      handoff_path: null,
+      feature_json_path: prdJson.source?.featureJson || null,
+      module: moduleCode
+    },
+    tasks: tasks,
+    history: []
+  };
+}
+```
+
+**If no queue exists:** proceed with standard logic below (backward compatible).
+
+---
+
 ### 1. Check for Existing prd.json
 
 **If `.ralph/prd.json` exists:**
@@ -38,16 +205,27 @@ Load the current task from prd.json or create initial task breakdown with catego
 - What layer does each task belong to?
 - What dependencies exist between tasks?
 
-**Check for BA handoff source:**
+**Check for BA handoff source (priority order):**
 
 ```bash
-# If a handoff document exists, use it to derive tasks
+# Priority 1: Per-module PRD files (from ss derive-prd / BA handoff)
+# These are already handled by Section 0 if modules-queue.json exists
+PRD_MODULE=$(ls .ralph/prd-*.json 2>/dev/null | head -1)
+
+# Priority 2: Single prd.json already present (from BA or previous run)
+PRD_SINGLE=".ralph/prd.json"
+
+# Priority 3: Markdown handoff document
 HANDOFF=$(find . -path "*development-handoff*" -name "*.md" | head -1)
 BA_OUTPUT=$(find . -path ".claude/output/ba/*" -name "4-*.md" | head -1)
 SOURCE_PATH=${HANDOFF:-$BA_OUTPUT}
 ```
 
-**If handoff found:**
+**If prd-*.json files exist but no modules-queue.json:**
+- This means step-00 didn't create a queue (single prd file)
+- Copy the single `prd-*.json` to `prd.json` and transform if needed
+
+**If markdown handoff found:**
 - Read the handoff document
 - Derive tasks from its specifications (per-layer breakdown)
 - Set `source.type = "ba-handoff"` and `source.handoff_path`
@@ -329,6 +507,7 @@ Read `.ralph/progress.txt` to understand:
 ```
 ╔══════════════════════════════════════════════════════════════════╗
 ║  ITERATION {current_iteration} / {max_iterations}               ║
+║  {modules_queue ? "Module " + (currentIndex+1) + "/" + totalModules + ": " + current_module : ""} ║
 ╠══════════════════════════════════════════════════════════════════╣
 ║  Progress: {tasks_completed} / {tasks_total} tasks complete     ║
 ║  Blocked:  {tasks_blocked}                                      ║

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

@@ -42,13 +42,14 @@ git commit -m "$(cat <<'EOF'
 
 Task {current_task_id}/{tasks_total} - Iteration {current_iteration}
 Category: {current_task_category}
+{current_module ? "Module: " + current_module : ""}
 
 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 EOF
 )"
 ```
 
-**Determine commit prefix from category:**
+**Determine commit prefix and scope:**
 
 | Category | Prefix | Scope |
 |----------|--------|-------|
@@ -62,6 +63,8 @@ EOF
 | `validation` | `chore` | validation |
 | `other` | `chore` | ralph |
 
+**Multi-module scope:** When `{current_module}` is set (from modules-queue.json), prefix the scope with the module code: `{PREFIX}({module}/{scope})`. Example: `feat(orders/OrderController): Create REST endpoints`.
+
 **Get commit hash:**
 ```bash
 COMMIT_HASH=$(git rev-parse --short HEAD)
@@ -176,11 +179,15 @@ Result: ✅ Met / ❌ Not met
 
 ```bash
 git add .ralph/prd.json .ralph/progress.txt
+# Also stage modules-queue.json if it exists (multi-module tracking)
+[ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
+
 git commit -m "$(cat <<'EOF'
 chore(ralph): update progress - task {current_task_id}/{tasks_total}
 
 Iteration {current_iteration} complete
 Status: {task.status}
+{current_module ? "Module: " + current_module : ""}
 
 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 EOF

package/templates/skills/ralph-loop/steps/step-04-check.md

@@ -67,6 +67,69 @@ writeJSON('.ralph/prd.json', prd);
 
 **If allDone = true:**
 
+**First, check for multi-module queue:**
+
+```javascript
+const queuePath = '.ralph/modules-queue.json';
+const hasQueue = fileExists(queuePath);
+
+if (hasQueue) {
+  const queue = readJSON(queuePath);
+  const currentModule = queue.modules[queue.currentIndex];
+
+  // Mark current module as completed
+  currentModule.status = 'completed';
+  queue.completedModules++;
+
+  // Check if more modules remain
+  const nextIndex = queue.currentIndex + 1;
+
+  if (nextIndex < queue.totalModules) {
+    // ADVANCE TO NEXT MODULE
+    queue.currentIndex = nextIndex;
+    queue.modules[nextIndex].status = 'in-progress';
+    writeJSON(queuePath, queue);
+
+    // Mark current prd.json as completed
+    prd.status = 'completed';
+    prd.updated_at = new Date().toISOString();
+    writeJSON('.ralph/prd.json', prd);
+
+    // Reset iteration counter for next module
+    // (preserve max_iterations from config)
+
+    console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║  ✅ MODULE COMPLETE: ${currentModule.code}                      ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Tasks: ${tasksCompleted} completed, ${tasksSkipped} skipped    ║
+║  Modules: ${queue.completedModules} / ${queue.totalModules}     ║
+╠══════════════════════════════════════════════════════════════════╣
+║  ADVANCING TO NEXT MODULE: ${queue.modules[nextIndex].code}     ║
+╚══════════════════════════════════════════════════════════════════╝
+    `);
+
+    // Loop back to step-01 which will load next module's prd
+    // -> Proceed to step-01-task.md
+    return;
+  }
+
+  // ALL MODULES COMPLETE - fall through to completion below
+  writeJSON(queuePath, queue);
+
+  console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║  ✅ ALL MODULES COMPLETE                                        ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Modules: ${queue.completedModules} / ${queue.totalModules}     ║
+║  ${queue.modules.map(m => m.code + ": " + m.status).join("\n║  ")} ║
+╚══════════════════════════════════════════════════════════════════╝
+  `);
+}
+```
+
+**Then output completion (single module or all modules done):**
+
 ```
 ╔══════════════════════════════════════════════════════════════════╗
 ║  ✅ ALL TASKS COMPLETE                                          ║
@@ -160,17 +223,16 @@ Continuing to next iteration...
    │ Reached      │   │ Done         │   │ Remaining    │
    └──────┬───────┘   └──────┬───────┘   └──────┬───────┘
           │                  │                   │
-          │                  │          ┌────────┴────────┐
-          │                  │          │                 │
-          ▼                  ▼          ▼                 ▼
-   ┌──────────────┐   ┌──────────────┐ ┌─────────────┐ ┌─────────────┐
-   │ Partial      │   │ Output       │ │ Dead-End    │ │ Loop to     │
-   │ Report       │   │ Promise      │ │ (all blocked│ │ step-01     │
-   │ step-05      │   │ step-05      │ │ or failed)  │ │             │
-   │ status:      │   │ status:      │ │ step-05     │ │             │
-   │ "partial"    │   │ "completed"  │ │ status:     │ │             │
-   └──────────────┘   └──────────────┘ │ "failed"    │ └─────────────┘
-                                       └─────────────┘
+          │         ┌────────┴────────┐  ┌───────┴────────┐
+          │         │                 │  │                │
+          ▼         ▼                 ▼  ▼                ▼
+   ┌────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+   │ Partial    │ │ More modules│ │ No more     │ │ Dead-End /  │
+   │ Report     │ │ in queue?   │ │ modules     │ │ Loop to     │
+   │ step-05    │ │ → step-01   │ │ → Promise   │ │ step-01     │
+   │ status:    │ │ (next mod)  │ │ → step-05   │ │             │
+   │ "partial"  │ └─────────────┘ └─────────────┘ └─────────────┘
+   └────────────┘
 ```
 
 ---
@@ -242,5 +304,7 @@ Completion Check:
 
 ## NEXT STEP:
 
-- If complete or max iterations or dead-end: `./step-05-report.md`
-- If tasks remaining: `./step-01-task.md`
+- If all tasks complete AND more modules in queue: `./step-01-task.md` (next module)
+- If all tasks complete AND no more modules (or no queue): `./step-05-report.md`
+- If max iterations or dead-end: `./step-05-report.md`
+- If tasks remaining in current module: `./step-01-task.md`

package/templates/skills/ralph-loop/steps/step-05-report.md

@@ -59,6 +59,70 @@ const filesModified = [...new Set(allFilesModified)];
 const totalDuration = prd.history.reduce((sum, h) => sum + (h.duration_seconds || 0), 0);
 ```
 
+### 1b. Multi-Module Aggregation (if modules-queue.json exists)
+
+**Check for multi-module context:**
+
+```javascript
+const queuePath = '.ralph/modules-queue.json';
+const hasQueue = fileExists(queuePath);
+
+let moduleStats = null;
+
+if (hasQueue) {
+  const queue = readJSON(queuePath);
+
+  moduleStats = {
+    totalModules: queue.totalModules,
+    completedModules: queue.completedModules,
+    modules: []
+  };
+
+  // Aggregate stats from each module's prd file
+  for (const mod of queue.modules) {
+    const modPrd = readJSON(mod.prdFile);
+    const modTasks = modPrd.tasks || [];
+
+    const modData = {
+      code: mod.code,
+      status: mod.status,
+      tasks: {
+        total: modTasks.length,
+        completed: modTasks.filter(t => t.status === 'completed').length,
+        failed: modTasks.filter(t => t.status === 'failed').length,
+        blocked: modTasks.filter(t => t.status === 'blocked').length,
+        skipped: modTasks.filter(t => t.status === 'skipped').length
+      },
+      filesCreated: [],
+      filesModified: [],
+      commits: []
+    };
+
+    for (const task of modTasks) {
+      if (task.files_changed) {
+        modData.filesCreated.push(...task.files_changed.created);
+        modData.filesModified.push(...task.files_changed.modified);
+      }
+      if (task.commit_hash) {
+        modData.commits.push(task.commit_hash);
+      }
+    }
+
+    modData.filesCreated = [...new Set(modData.filesCreated)];
+    modData.filesModified = [...new Set(modData.filesModified)];
+    modData.commits = [...new Set(modData.commits)];
+
+    moduleStats.modules.push(modData);
+  }
+
+  // Merge all module files into main aggregation
+  for (const mod of moduleStats.modules) {
+    allFilesCreated.push(...mod.filesCreated);
+    allFilesModified.push(...mod.filesModified);
+  }
+}
+```
+
 ### 2. Collect MCP Usage (from logs if available)
 
 **Parse from verbose logs:**
@@ -111,6 +175,18 @@ const validationStats = {
 
 {status_emoji mapping: completed=✅, failed=❌, blocked=🚫, skipped=⏭️, pending=⏳}
 
+{if moduleStats:}
+## Module Progress
+
+| Module | Status | Tasks | Completed | Failed | Files Created | Files Modified | Commits |
+|--------|--------|-------|-----------|--------|---------------|----------------|---------|
+{for each mod in moduleStats.modules:}
+| {mod.code} | {mod.status} | {mod.tasks.total} | {mod.tasks.completed} | {mod.tasks.failed} | {mod.filesCreated.length} | {mod.filesModified.length} | {mod.commits.length} |
+{end for}
+
+**Modules: {moduleStats.completedModules}/{moduleStats.totalModules} completed**
+{end if}
+
 ## Failed Tasks
 
 {if any failed tasks:}
@@ -216,6 +292,7 @@ writeJSON('.ralph/prd.json', prd);
 ║  Iterations: {iterations_used}                                   ║
 ║  Tasks:      {completed}/{total} completed                       ║
 ║              {failed} failed, {blocked} blocked                  ║
+║  {moduleStats ? "Modules: " + moduleStats.completedModules + "/" + moduleStats.totalModules + " completed" : ""} ║
 ╠══════════════════════════════════════════════════════════════════╣
 ║  Files Created:  {filesCreated.length}                           ║
 ║  Files Modified: {filesModified.length}                          ║
@@ -262,6 +339,8 @@ Next steps:
 - Duration calculated from history entries
 - Final summary displayed
 - prd.json `status` and `updated_at` finalized
+- **Multi-module:** Per-module statistics table included (if modules-queue.json exists)
+- **Multi-module:** Cross-module file and commit aggregation
 
 ## COMPLETION: