@atlashub/smartstack-cli 3.1.0 → 3.2.0

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

@@ -10,27 +10,38 @@ Execute the Ralph Weegund technique - an iterative development methodology where
 </objective>
 
 <quick_start>
-**Basic usage:**
-
-```bash
-/ralph-loop implement user authentication
-```
-
-**With completion promise:**
+**Three ways to start Ralph Loop:**
+
+1. **From Business Analysis (RECOMMENDED - NEW v6.1):**
+   ```bash
+   /business-analyse MyFeature
+   # At the end, choose "Ralph Loop" → automatic launch
+   # No arguments needed - prd.json already generated
+   ```
+
+2. **Manual start with existing prd.json:**
+   ```bash
+   /ralph-loop
+   # Ralph detects .ralph/prd.json and resumes automatically
+   # Works after BA handoff or previous Ralph session
+   ```
+
+3. **Direct task (no BA):**
+   ```bash
+   /ralph-loop implement user authentication
+   # Ralph creates prd.json on the fly
+   ```
+
+**With options:**
 
 ```bash
+# Completion promise
 /ralph-loop -c "COMPLETE" refactor the cache layer
-```
 
-**With max iterations:**
-
-```bash
+# Max iterations
 /ralph-loop -m 20 -c "TESTS PASS" add comprehensive tests
-```
 
-**Verbose mode:**
-
-```bash
+# Verbose mode
 /ralph-loop -v -c "DONE" fix all linting errors
 ```
 
@@ -39,6 +50,7 @@ Execute the Ralph Weegund technique - an iterative development methodology where
 - `-m N` (max): Maximum iterations before auto-stop
 - `-c TEXT` (complete): Completion promise text
 - `-v` (verbose): Detailed logging
+- `-r` (resume): Resume from previous state
 
 See `<parameters>` for complete flag list.
 </quick_start>
@@ -99,12 +111,75 @@ The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes
 5. Claude sees previous work in the files
 6. Iteratively improves until completion promise is output
 
+**Iterative Development Cycle (per task):**
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   RALPH LOOP - CYCLE                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. ANALYSE      → Load next task from prd.json            │
+│                    (UC, FR, BR, wireframes, acceptance)     │
+│                                                             │
+│  2. DÉVELOPPEMENT → Generate code for task                  │
+│     ├─ Backend:   Entity, Service, Repository, Controller  │
+│     ├─ Tests:     Unit tests (xUnit) + non-regression      │
+│     ├─ Frontend:  Page, Component, Hook (match wireframe)  │
+│     ├─ Tests:     Frontend tests (React Testing Library)   │
+│     ├─ SeedData:  CORE RBAC (5 entries) + business data    │
+│     └─ Docs:      Inline comments + tooltips + i18n keys   │
+│                                                             │
+│  3. VALIDATION   → Commit changes + MCP conventions check   │
+│                    (validate_conventions, check_migrations) │
+│                                                             │
+│  4. TEST         → Run tests (dotnet test + npm test)       │
+│                    ├─ Unit tests                            │
+│                    ├─ Integration tests                     │
+│                    ├─ Security tests (tenant isolation)     │
+│                    └─ E2E tests (critical flows)            │
+│                                                             │
+│  5. CORRECTION   → If tests fail:                           │
+│                    ├─ Analyze error logs                    │
+│                    ├─ Fix root cause                        │
+│                    ├─ Commit fix                            │
+│                    └─ Return to step 4                      │
+│                                                             │
+│  6. NEXT TASK    → Mark task as completed, loop to step 1   │
+│                                                             │
+│  🎯 Goal: 100% tests pass before moving to next task        │
+│  📊 Coverage: 95-100% (tests auto-generated)                │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
 **Completion signal:**
 ```
 <promise>{completion_promise}</promise>
 ```
 
 The loop only stops when this exact tag is output or max iterations reached.
+
+**What Ralph generates per task:**
+- **Backend code**: Entities (Domain), Services (Application), Repositories (Infrastructure), Controllers (API)
+- **Unit tests**: xUnit tests for domain logic, services, repositories
+- **Integration tests**: Controller tests with WebApplicationFactory
+- **Frontend code**: React pages, components, custom hooks (matching BA wireframes)
+- **Frontend tests**: React Testing Library for components and pages
+- **SeedData**: 5 CORE entries (Navigation, Permissions, Roles, Tenants, Users) + business reference data
+- **Documentation**: Inline code comments, user-facing tooltips, i18n translation keys
+- **Security tests**: Tenant isolation, permission checks, OWASP validations
+
+**prd.json structure (input from BA):**
+The prd.json is generated by `/business-analyse` via `ss derive-prd` command. It contains:
+- **feature**: Feature description (from BA)
+- **tasks[]**: Task breakdown by category (domain, application, infrastructure, api, frontend, i18n, test, validation)
+  - Each task has: id, description, category, dependencies, acceptance_criteria, linkedFRs, linkedUCs, linkedBRs
+  - Frontend tasks include: linkedWireframes (screen IDs from BA mockups), wireframeAcceptanceCriteria
+  - SeedData tasks specify: category (core|business), source (specification.seedDataCore or seedDataBusiness)
+- **source**: Traceability to feature.json path (source of truth)
+- **metadata**: Project context (branch, namespace, module order)
+- **config**: max_iterations, completion_promise, current_iteration
+
+Ralph reads prd.json to know WHAT to generate, then generates it, tests it, fixes it, and moves to the next task.
 </ralph_concept>
 
 <workflow>
@@ -118,19 +193,62 @@ The loop only stops when this exact tag is output or max iterations reached.
 7. Check completion → enter COMPACT LOOP (step-04)
 8. **COMPACT LOOP** (step-04 section 5, NO re-reading step files):
    - Find eligible tasks → batch by category (max 5)
-   - Execute batch inline
-   - Commit batch
+   - Execute batch inline (generate code)
+   - Run tests (dotnet test + npm test)
+   - If tests fail: analyze → fix → re-test (loop until 100% pass)
+   - Commit batch (only when tests pass)
    - Re-check completion → loop or finish
 9. When complete: generate final report (step-05)
 
-**Multi-module flow (from BA handoff):**
-1-3. Same as standard flow
+**Multi-module flow (from BA handoff - NEW v6.1: automatic launch):**
+1-3. Same as standard flow (or launched automatically from `/business-analyse`)
 4. Detect `prd-*.json` files → create `modules-queue.json`
 5. Copy current module's prd to `prd.json`
-6. Execute all tasks for current module via COMPACT LOOP
+6. Execute all tasks for current module via COMPACT LOOP:
+   - Process tasks by category (domain → seeddata → application → infrastructure → api → frontend → i18n → tests)
+   - For each task: generate → test → fix (if needed) → re-test → commit (when pass)
+   - Each task generates: backend code + tests + frontend code + tests + seeddata + docs
+   - Each frontend task respects wireframes from BA (specification.uiWireframes[])
+   - Continue until ALL tasks of module = completed
 7. When module complete: advance to next module in queue (step-04 section 3)
 8. Repeat steps 5-7 for each module (step-01 is re-read ONLY for module transitions)
 9. When all modules done: generate cross-module report
+
+**Note:** When launched from `/business-analyse` (v6.1+), Ralph Loop receives:
+- `.ralph/prd-{module}.json` for each module (generated by `ss derive-prd`)
+  - Each prd contains: tasks breakdown with UC/FR/BR/wireframes/acceptance criteria
+  - Task categories: domain, application, infrastructure, api, frontend, i18n, test, validation
+  - Each task linked to: functional requirements (FR), use cases (UC), business rules (BR)
+  - Frontend tasks include: linkedWireframes[] (screen IDs from BA mockups)
+  - SeedData tasks specify: category (core 5 entries MANDATORY + business data)
+- `.ralph/progress.txt` with comprehensive task tracker (hierarchical: module → layer → tasks)
+- Module order from BA's topological dependency graph (dependencies first)
+- No arguments needed - fully configured by BA handoff
+
+**Task execution cycle (per task):**
+```
+LOAD TASK → GENERATE CODE → COMMIT → RUN TESTS → [FAIL?] → ANALYZE ERROR → FIX → RE-TEST → [PASS!] → NEXT TASK
+                                                    ↑___________________________________________|
+                                                         (loop until 100% tests pass)
+```
+
+**What gets generated per module:**
+1. **Domain layer**: Entities, Value Objects, Enums, Domain Exceptions
+2. **SeedData layer**: 5 CORE entries (Navigation, Permissions, Roles, Tenants, Users) + business reference data
+3. **Application layer**: Services, DTOs, Validators, Query Handlers
+4. **Infrastructure layer**: Repositories, DbContext, Specifications
+5. **API layer**: Controllers, Error Handlers, Validation Responses
+6. **Frontend layer**: Pages (matching wireframes), Components, Custom Hooks, Forms
+7. **I18n layer**: Translation keys (fr, en, it, de) for UI labels
+8. **Tests layer**: Unit tests (Domain, Application), Integration tests (API), Security tests (tenant isolation), E2E tests (critical flows)
+
+**Acceptance criteria per task:**
+- Code compiles (dotnet build + npm build)
+- Tests pass (dotnet test + npm test)
+- MCP conventions validated (validate_conventions)
+- Wireframes respected (frontend pages match BA mockups from specification.uiWireframes[])
+- Business rules implemented (BR-to-code mapping from BA)
+- Security enforced (tenant isolation, RBAC permissions)
 </workflow>
 
 <state_variables>

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

@@ -6,11 +6,35 @@ next_step: steps/step-02-execute.md
 
 # Step 1: Load Task
 
-> **CONTEXT OPTIMIZATION:** This file is only read ONCE (first iteration).
+> **MODULE TRANSITION CHECK (MANDATORY):**
+> Before applying the "Only Read Once" rule, check for module transition marker:
+
+```javascript
+const moduleChangedPath = '.ralph/module-changed.json';
+const moduleTransition = fileExists(moduleChangedPath);
+
+if (moduleTransition) {
+  const transitionData = readJSON(moduleChangedPath);
+  console.log(`🔄 Module transition detected: ${transitionData.fromModule} → ${transitionData.toModule}`);
+  console.log(`   Reloading step-01 to initialize new module...`);
+
+  // Delete flag (consume it)
+  deleteFile(moduleChangedPath);
+
+  // PROCEED with step-01 execution (skip "Only Read Once" rule below)
+  // This is the EXCEPTION case for multi-module workflows
+}
+```
+
+> **CONTEXT OPTIMIZATION:** This file is normally read ONCE per module (first iteration).
 > After the first full iteration (step-01 → step-02 → step-03 → step-04),
-> ALL subsequent iterations MUST use the COMPACT LOOP in step-04-check.md section 5.
-> **DO NOT re-read this file for iterations > 1.**
-> If you are re-reading this file on iteration > 1, STOP and go to step-04 section 5 instead.
+> ALL subsequent iterations within the SAME module MUST use the COMPACT LOOP in step-04-check.md section 5.
+> **DO NOT re-read this file for iterations > 1 of the same module.**
+>
+> **EXCEPTION:** When transitioning between modules (multi-module workflows), step-01 MUST be re-read
+> to load the next module's PRD. This is signaled by `.ralph/module-changed.json` file (checked above).
+>
+> If you are re-reading this file on iteration > 1 AND no module transition detected, STOP and go to step-04 section 5 instead.
 
 ## YOUR TASK:
 
@@ -24,7 +48,10 @@ Load the current task from prd.json or create initial task breakdown with catego
 
 ### 0. Multi-Module Queue Check
 
-**Before any other logic, check for modules-queue.json:**
+**✅ ALWAYS check for modules-queue.json, even on iteration > 1:**
+
+> **CRITICAL:** This section MUST execute even when step-01 is re-read for module transitions.
+> The module-changed.json flag (checked above) ensures this section runs when needed.
 
 ```javascript
 const queuePath = '.ralph/modules-queue.json';
@@ -34,22 +61,52 @@ 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);
+  console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║  Multi-Module Workflow Detected                                 ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Current Module: ${currentModule.code} (${queue.currentIndex + 1}/${queue.totalModules})                    ║
+║  Status: ${currentModule.status}                                ║
+║  PRD File: ${currentModule.prdFile}                             ║
+╚══════════════════════════════════════════════════════════════════╝
+  `);
+
+  // ✅ FIX #3: RESTORE multi-module state variables
+  // These variables persist across step files and are critical for multi-module coordination
+  {modules_queue} = queue;
+  {current_module} = currentModule.code;
+
+  // ✅ Load or verify current module's PRD is in .ralph/prd.json
+  // On module transition, step-04 already loaded it, but we verify here
+  const currentPrd = readJSON('.ralph/prd.json');
+
+  // Verify PRD matches current module (sanity check)
+  if (currentPrd.metadata && currentPrd.metadata.moduleCode !== currentModule.code) {
+    console.log(`⚠️  PRD mismatch detected. Loading correct PRD for module ${currentModule.code}...`);
+
+    // Load current module's PRD
+    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);
+      console.log(`✅ Transformed and loaded PRD for module: ${currentModule.code}`);
+    } else {
+      // Already Ralph v2 format
+      writeJSON('.ralph/prd.json', modulePrd);
+      console.log(`✅ Loaded PRD for module: ${currentModule.code}`);
+    }
   } else {
-    // Already Ralph v2 format
-    writeJSON('.ralph/prd.json', modulePrd);
+    console.log(`✅ PRD already loaded for module: ${currentModule.code}`);
   }
 
-  console.log(`Loaded PRD for module: ${currentModule.code}`);
+  console.log(`State restored: modules_queue and current_module set`);
+} else {
+  // Single-module workflow
+  {modules_queue} = null;
+  {current_module} = null;
 }
 ```
 

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

@@ -181,13 +181,25 @@ if (hasQueue) {
     queue.modules[nextIndex].status = 'in-progress';
     writeJSON(queuePath, queue);
 
+    // ✅ FIX #1: Create module transition marker
+    // This signals to step-01 that it MUST reload even on iteration > 1
+    writeJSON('.ralph/module-changed.json', {
+      fromModule: currentModule.code,
+      toModule: queue.modules[nextIndex].code,
+      timestamp: new Date().toISOString()
+    });
+
     // 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)
+    // ✅ FIX #2: Load next module's PRD NOW and reset iteration counter
+    const nextModulePrd = readJSON(queue.modules[nextIndex].prdFile);
+    nextModulePrd.config.current_iteration = 1;
+    nextModulePrd.config.max_iterations = prd.config.max_iterations; // Preserve
+    nextModulePrd.updated_at = new Date().toISOString();
+    writeJSON('.ralph/prd.json', nextModulePrd);
 
     console.log(`
 ╔══════════════════════════════════════════════════════════════════╗
@@ -197,10 +209,13 @@ if (hasQueue) {
 ║  Modules: ${queue.completedModules} / ${queue.totalModules}     ║
 ╠══════════════════════════════════════════════════════════════════╣
 ║  ADVANCING TO NEXT MODULE: ${queue.modules[nextIndex].code}     ║
+║  Next module PRD loaded: ${queue.modules[nextIndex].prdFile}    ║
+║  Iteration counter reset: 1                                      ║
 ╚══════════════════════════════════════════════════════════════════╝
     `);
 
-    // Loop back to step-01 which will load next module's prd
+    // Loop back to step-01 which will detect module-changed.json
+    // and skip the "Only Read Once" rule for this transition
     // -> Proceed to step-01-task.md
     return;
   }
@@ -347,8 +362,60 @@ Batch: {tasksToExecute.length} task(s) [{firstCategory}]
 1. Mark `task.status = 'in_progress'`, `task.started_at = now`
 2. ULTRA THINK: implement the task following SmartStack conventions
    - Track files_created and files_modified per task
-3. Verify acceptance criteria
-4. If failed: set `task.status = 'failed'`, `task.error = reason`, continue to next task in batch
+3. **MANDATORY TEST-DRIVEN CYCLE (per task):**
+   ```
+   ┌─────────────────────────────────────────────────────────┐
+   │  TASK EXECUTION CYCLE (100% tests pass required)       │
+   ├─────────────────────────────────────────────────────────┤
+   │                                                         │
+   │  1. GENERATE CODE                                       │
+   │     ├─ Backend:  Entity, Service, Repository, Controller│
+   │     ├─ Frontend: Page, Component, Hook                 │
+   │     ├─ Tests:    Unit tests + Integration tests        │
+   │     └─ Docs:     Inline comments + tooltips + i18n     │
+   │                                                         │
+   │  2. COMPILE CODE                                        │
+   │     ├─ Backend:  dotnet build --no-restore             │
+   │     └─ Frontend: npm run typecheck                     │
+   │                                                         │
+   │  3. RUN TESTS (MANDATORY)                               │
+   │     ├─ Backend:  dotnet test {TestProject}             │
+   │     ├─ Frontend: npm test (if applicable)              │
+   │     └─ Security: tenant isolation + RBAC checks        │
+   │                                                         │
+   │  4. CHECK RESULT                                        │
+   │     ├─ IF 100% PASS → Mark task completed, next task   │
+   │     └─ IF ANY FAIL  → Go to step 5                     │
+   │                                                         │
+   │  5. FIX ERRORS (loop until pass)                        │
+   │     ├─ Parse test output → identify failing tests      │
+   │     ├─ Analyze root cause (stack trace, logs)          │
+   │     ├─ Fix code (NOT test - fix implementation)        │
+   │     ├─ Re-compile (step 2)                             │
+   │     └─ Re-run tests (step 3) → loop until 100% pass    │
+   │                                                         │
+   │  🎯 Goal: ZERO test failures before next task           │
+   │  📊 Coverage: 95-100% (tests auto-generated per task)   │
+   │                                                         │
+   └─────────────────────────────────────────────────────────┘
+   ```
+
+   **Implementation per task:**
+   a. Generate code + tests
+   b. Compile: `dotnet build` or `npm run typecheck`
+   c. Run tests: `dotnet test {TestProject}` or `npm test`
+   d. Parse test output → count passed/failed/skipped
+   e. IF failed > 0:
+      - Log failure details to progress.txt
+      - Analyze error (stack trace, assertion message)
+      - Fix code (modify implementation, NOT test)
+      - Re-compile
+      - Re-run tests
+      - Repeat until passed = total (100%)
+   f. IF passed = total → task.status = 'completed'
+
+4. Verify acceptance criteria
+5. If task execution failed (not tests, but code generation): set `task.status = 'failed'`, `task.error = reason`, continue to next task in batch
 
 **CATEGORY-SPECIFIC EXECUTION RULES:**