@atlashub/smartstack-cli 3.0.0 → 3.2.0

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

@@ -1,14 +1,19 @@
 ---
 name: step-02-execute
-description: Execute ONE task with dependency checks and rich tracking
+description: Execute task(s) with dependency checks and rich tracking
 next_step: steps/step-03-commit.md
 ---
 
 # Step 2: Execute Task
 
+> **CONTEXT OPTIMIZATION:** This file is only read ONCE (first iteration).
+> After the first full iteration, ALL subsequent iterations use the COMPACT LOOP
+> in step-04-check.md section 5 which includes inline execution.
+> **DO NOT re-read this file for iterations > 1.**
+
 ## YOUR TASK:
 
-Execute exactly ONE task from prd.json. Do NOT batch multiple tasks.
+Execute the current task(s) from prd.json. For the first iteration, execute ONE task. After the first iteration, the compact loop in step-04 handles batch execution.
 
 **ULTRA THINK about the implementation.**
 
@@ -16,12 +21,11 @@ Execute exactly ONE task from prd.json. Do NOT batch multiple tasks.
 
 ## EXECUTION RULES:
 
-1. **ONE TASK ONLY** - Execute only `{current_task_description}`
-2. **ATOMIC CHANGES** - Changes should be complete and working
-3. **USE MCP** - Validate with SmartStack MCP as needed
-4. **DOCUMENT** - Track what you're doing
-5. **CHECK DEPENDENCIES** - Verify all dependencies are met before starting
-6. **TRACK FILES** - Record every file created or modified
+1. **ATOMIC CHANGES** - Changes should be complete and working
+2. **USE MCP** - Validate with SmartStack MCP (once per batch, not per task)
+3. **TRACK FILES** - Record every file created or modified
+4. **CHECK DEPENDENCIES** - Verify all dependencies are met before starting
+5. **BATCH ALLOWED** - Multiple tasks of the same category can be batched (max 5)
 
 ---
 
@@ -81,6 +85,352 @@ writeJSON('.ralph/prd.json', prd);
 | `test` | `scaffold_tests`, `analyze_test_coverage` | xUnit, test naming conventions |
 | `validation` | `validate_conventions` | Build, test, lint checks |
 
+**Test task guidance — TDD CYCLE (MANDATORY):**
+
+> **CRITICAL:** Tests are NOT optional. Every feature MUST have tests that pass.
+> The cycle is: Generate Code → Generate Tests → Run Tests → Fix Code → Re-run Tests → Pass.
+
+When executing `test` category tasks, follow this EXACT sequence:
+
+**1. ENSURE TEST PROJECT EXISTS (BLOCKING)**
+
+```bash
+# Detect project name from solution
+PROJECT_NAME=$(basename $(pwd))
+TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
+
+if [ ! -d "$TEST_PROJECT" ]; then
+  echo "⚠️  Test project missing. Scaffolding now..."
+
+  # Create test project
+  dotnet new xunit -n "${PROJECT_NAME}.Tests.Unit" -o "$TEST_PROJECT"
+
+  # Add required packages
+  cd "$TEST_PROJECT"
+  dotnet add package Moq --version 4.20.72
+  dotnet add package FluentAssertions --version 8.3.0
+  dotnet add package Microsoft.Extensions.DependencyInjection --version 10.0.2
+  cd ../..
+
+  # Add project references to all src/ projects
+  for proj in src/*/*.csproj; do
+    dotnet add "$TEST_PROJECT" reference "$proj"
+  done
+
+  # Add test project to solution
+  dotnet sln add "$TEST_PROJECT/${PROJECT_NAME}.Tests.Unit.csproj"
+
+  echo "✅ Test project scaffolded at $TEST_PROJECT"
+fi
+```
+
+**2. GENERATE TESTS USING MCP (DO NOT WRITE MANUALLY)**
+
+```javascript
+// Identify what to test based on task description
+const task = prd.tasks.find(t => t.id === {current_task_id});
+const testType = detectTestType(task.description); // "unit" | "integration" | "security"
+
+// For domain tests
+if (task.description.includes("domain entity") || task.description.includes("value object")) {
+  // Call MCP to scaffold domain tests
+  mcp__smartstack__scaffold_tests({
+    module: extractModuleName(task.description),
+    test_type: "unit",
+    target_layer: "domain",
+    target_file: identifyEntityFile(task.description)
+  });
+}
+
+// For service tests
+if (task.description.includes("service")) {
+  mcp__smartstack__scaffold_tests({
+    module: extractModuleName(task.description),
+    test_type: "unit",
+    target_layer: "application",
+    target_file: identifyServiceFile(task.description)
+  });
+}
+
+// For controller tests
+if (task.description.includes("controller") || task.description.includes("API")) {
+  mcp__smartstack__scaffold_tests({
+    module: extractModuleName(task.description),
+    test_type: "integration",
+    target_layer: "api",
+    target_file: identifyControllerFile(task.description)
+  });
+}
+
+// For security/permissions tests
+if (task.description.includes("permission") || task.description.includes("security")) {
+  mcp__smartstack__scaffold_tests({
+    module: extractModuleName(task.description),
+    test_type: "security",
+    target_layer: "api",
+    target_file: identifyControllerFile(task.description)
+  });
+}
+```
+
+**3. RUN TESTS IMMEDIATELY (BLOCKING)**
+
+```bash
+# Build test project first
+dotnet build "$TEST_PROJECT" --no-restore
+
+# Run tests with detailed output
+dotnet test "$TEST_PROJECT" --no-build --verbosity normal
+
+# Capture exit code
+TEST_EXIT_CODE=$?
+```
+
+**4. ANALYZE RESULTS AND IMPROVE (LOOP UNTIL GREEN)**
+
+```javascript
+if (TEST_EXIT_CODE !== 0) {
+  echo "❌ Tests failed. Analyzing failures...";
+
+  // Parse test output to identify failures
+  const failures = parseTestFailures(testOutput);
+
+  // CRITICAL: DO NOT PROCEED. Fix the code.
+  for (const failure of failures) {
+    echo `  - ${failure.testName}: ${failure.reason}`;
+
+    // Identify what needs fixing
+    if (failure.reason.includes("NullReferenceException")) {
+      // Fix null handling in implementation
+    } else if (failure.reason.includes("Expected") && failure.reason.includes("Actual")) {
+      // Fix logic to match expected behavior
+    } else if (failure.reason.includes("NotImplementedException")) {
+      // Implement missing method
+    }
+  }
+
+  // After fixes, RE-RUN TESTS (step 3)
+  // LOOP until TEST_EXIT_CODE === 0
+
+  // If cannot fix after 3 attempts:
+  task.status = 'failed';
+  task.error = `Tests failed after 3 fix attempts: ${failures.map(f => f.testName).join(', ')}`;
+  // STOP - do not proceed to commit
+}
+
+if (TEST_EXIT_CODE === 0) {
+  echo "✅ All tests passed!";
+  {validation_result} = "passed";
+}
+```
+
+**5. VERIFY TEST COVERAGE (MANDATORY ≥80%)**
+
+```javascript
+// Use MCP to analyze coverage
+const coverage = mcp__smartstack__analyze_test_coverage({
+  project_path: process.cwd(),
+  module: extractModuleName(task.description)
+});
+
+if (coverage.percentage < 80) {
+  echo `⚠️  Test coverage ${coverage.percentage}% < 80% minimum`;
+  echo `Missing coverage for: ${coverage.uncovered_files.join(', ')}`;
+
+  // Generate additional tests for uncovered code
+  for (const file of coverage.uncovered_files) {
+    mcp__smartstack__scaffold_tests({
+      module: extractModuleName(task.description),
+      test_type: "unit",
+      target_file: file
+    });
+  }
+
+  // Re-run tests (go back to step 3)
+}
+
+echo `✅ Test coverage: ${coverage.percentage}% (${coverage.lines_covered}/${coverage.lines_total} lines)`;
+```
+
+**6. TEST TASK COMPLETION CRITERIA**
+
+A test task is ONLY complete when:
+- ✅ Test project exists
+- ✅ Tests generated via MCP (NOT manually written)
+- ✅ `dotnet test` exits with code 0 (all tests pass)
+- ✅ Test coverage ≥ 80%
+- ✅ No `[Fact(Skip = "...")]` present (no skipped tests)
+
+**If ANY criterion fails, task.status = 'failed' and DO NOT commit.**
+
+**Validation task guidance — FINAL VERIFICATION (BLOCKING):**
+
+> **CRITICAL:** The validation task is the LAST task in each module. It verifies the module is production-ready.
+
+When executing `validation` category tasks, follow this EXACT sequence:
+
+**1. CLEAN BUILD (MANDATORY)**
+
+```bash
+echo "🔨 Running clean build..."
+
+# Clean previous builds
+dotnet clean --verbosity quiet
+
+# Restore dependencies
+dotnet restore --verbosity quiet
+
+# Build entire solution
+dotnet build --no-restore --verbosity normal
+
+BUILD_EXIT_CODE=$?
+
+if [ $BUILD_EXIT_CODE -ne 0 ]; then
+  echo "╔════════════════════════════════════════════════════════════╗"
+  echo "║  ❌ BUILD FAILED                                          ║"
+  echo "╠════════════════════════════════════════════════════════════╣"
+  echo "║  The solution does not compile.                            ║"
+  echo "║  This indicates a critical error in the code.              ║"
+  echo "╠════════════════════════════════════════════════════════════╣"
+  echo "║  CORRECTIVE ACTION:                                        ║"
+  echo "║  1. Review build errors above                              ║"
+  echo "║  2. Fix compilation errors                                 ║"
+  echo "║  3. Re-run: dotnet build                                   ║"
+  echo "║  4. Once build succeeds, Ralph will continue               ║"
+  echo "╚════════════════════════════════════════════════════════════╝"
+
+  task.status = 'failed';
+  task.error = 'Build failed. See build output for details.';
+  exit 1;
+fi
+
+echo "✅ Build succeeded";
+```
+
+**2. RUN FULL TEST SUITE (MANDATORY)**
+
+```bash
+echo "🧪 Running full test suite..."
+
+PROJECT_NAME=$(basename $(pwd))
+TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
+
+if [ ! -d "$TEST_PROJECT" ]; then
+  echo "⚠️  WARNING: No test project found at $TEST_PROJECT";
+  echo "This module has NO tests. This is NOT recommended.";
+  task.validation = "warning: no tests";
+else
+  # Run ALL tests with detailed output
+  dotnet test "$TEST_PROJECT" --no-build --verbosity normal --logger "console;verbosity=detailed"
+
+  TEST_EXIT_CODE=$?
+
+  if [ $TEST_EXIT_CODE -ne 0 ]; then
+    echo "╔════════════════════════════════════════════════════════════╗"
+    echo "║  ❌ TESTS FAILED                                          ║"
+    echo "╠════════════════════════════════════════════════════════════╣"
+    echo "║  One or more tests are failing.                            ║"
+    echo "║  The module is NOT production-ready.                       ║"
+    echo "╠════════════════════════════════════════════════════════════╣"
+    echo "║  CORRECTIVE ACTION:                                        ║"
+    echo "║  1. Review test failures above                             ║"
+    echo "║  2. Fix the failing code or tests                          ║"
+    echo "║  3. Re-run: dotnet test                                    ║"
+    echo "║  4. Once all tests pass, Ralph will continue               ║"
+    echo "╚════════════════════════════════════════════════════════════╝"
+
+    task.status = 'failed';
+    task.error = 'Test suite failed. Module not production-ready.';
+    exit 1;
+  fi
+
+  echo "✅ All tests passed";
+fi
+```
+
+**3. MCP VALIDATION (MANDATORY)**
+
+```javascript
+echo "🔍 Running MCP validation...";
+
+// Validate SmartStack conventions
+const validation = mcp__smartstack__validate_conventions({
+  checks: ["all"]
+});
+
+if (validation.status === "error" || validation.errors.length > 0) {
+  echo "❌ MCP validation failed:";
+  for (const error of validation.errors) {
+    echo `  - ${error.file}: ${error.message}`;
+  }
+
+  task.status = 'failed';
+  task.error = `MCP validation failed: ${validation.errors.length} error(s)`;
+  exit 1;
+}
+
+if (validation.warnings.length > 0) {
+  echo "⚠️  MCP validation warnings:";
+  for (const warning of validation.warnings) {
+    echo `  - ${warning.file}: ${warning.message}`;
+  }
+  task.validation = `passed with ${validation.warnings.length} warning(s)`;
+} else {
+  task.validation = "passed";
+}
+
+echo "✅ MCP validation passed";
+```
+
+**4. GENERATE VALIDATION REPORT**
+
+```javascript
+const report = {
+  module: {current_module},
+  build: { status: "success", duration: buildDuration },
+  tests: {
+    status: TEST_EXIT_CODE === 0 ? "success" : "failed",
+    total: testStats.total,
+    passed: testStats.passed,
+    failed: testStats.failed,
+    skipped: testStats.skipped,
+    duration: testStats.duration,
+    coverage: coverage.percentage
+  },
+  mcp: {
+    status: validation.status,
+    errors: validation.errors.length,
+    warnings: validation.warnings.length
+  },
+  production_ready: (BUILD_EXIT_CODE === 0 && TEST_EXIT_CODE === 0 && validation.errors.length === 0)
+};
+
+// Append to progress.txt
+const progressEntry = `
+╔═══════════════════════════════════════════════════════════════╗
+║  MODULE VALIDATION REPORT - ${current_module}
+╠═══════════════════════════════════════════════════════════════╣
+║  Build:    ${report.build.status.toUpperCase()}
+║  Tests:    ${report.tests.passed}/${report.tests.total} passed (${report.tests.coverage}% coverage)
+║  MCP:      ${report.mcp.status.toUpperCase()} (${report.mcp.errors} errors, ${report.mcp.warnings} warnings)
+║  Production Ready: ${report.production_ready ? "YES ✅" : "NO ❌"}
+╚═══════════════════════════════════════════════════════════════╝
+`;
+appendToFile('.ralph/progress.txt', progressEntry);
+
+echo progressEntry;
+```
+
+**5. VALIDATION TASK COMPLETION CRITERIA**
+
+A validation task is ONLY complete when:
+- ✅ `dotnet build` exits with code 0
+- ✅ `dotnet test` exits with code 0 (or no test project + warning logged)
+- ✅ MCP `validate_conventions` has 0 errors
+- ✅ Production ready = true
+
+**If ANY criterion fails, task.status = 'failed', module is NOT production-ready, and Ralph STOPS.**
+
 **Infrastructure task guidance (MANDATORY directory conventions):**
 
 When executing `infrastructure` category tasks, follow these rules strictly:
@@ -108,26 +458,61 @@ When executing `infrastructure` category tasks, follow these rules strictly:
    - Use `SqlObjectHelper.cs` for embedded resource loading
    - Use `CREATE OR ALTER` in SQL files for idempotency
 
-**Frontend task guidance (MANDATORY Layout wrapper):**
+**Frontend task guidance — MCP-FIRST PROTOCOL (MANDATORY):**
+
+> **CRITICAL:** Frontend code is generated via MCP tools, NOT written from scratch.
+> Writing plain HTML tables, custom div cards, or hardcoded Tailwind is FORBIDDEN.
+> The MCP tools produce SmartStack-compliant code automatically.
 
-When executing `frontend` category tasks, follow these rules strictly:
+**Execution sequence for frontend tasks (follow IN ORDER):**
 
-1. **Routes MUST be inside Layout wrapper** (CRITICAL - violating this breaks the entire UI shell)
-   - All routes MUST be nested inside the appropriate context Layout component
-   - `platform.*` → `<Route path="/platform" element={<AdminLayout />}>` children
-   - `business.*` → `<Route path="/business" element={<BusinessLayout />}>` children
-   - `personal.*` → `<Route path="/personal/myspace" element={<UserLayout />}>` children
-   - **If routes are placed OUTSIDE the layout wrapper: header, sidebar, and AvatarMenu will NOT render**
-   - NEVER create flat routes at the top level of `<Routes>`
+1. **Call `mcp__smartstack__scaffold_api_client`** FIRST
+   - Generates: `{entity}Api.ts` with type-safe CRUD methods + React Query hook
+   - Uses `apiClient` (NOT axios), NavRoute integration, permission checking
+   - Output: `src/services/api/{module}Api.ts`
 
-2. **Nested routes, NOT flat routes**
-   - Use `<Route path="application"><Route path="module" element={...} /></Route>` pattern
-   - NEVER use `<Route path="/context/application/module" element={...} />` (flat)
-   - Use `<Route index element={<Navigate to="default" replace />} />` for default redirects
+2. **Call `mcp__smartstack__scaffold_routes`** (source: "controllers", scope: "all")
+   - Updates: `navRoutes.generated.ts` + route config in App.tsx
+   - Generates: Nested routes INSIDE correct Layout wrapper
+   - Context mapping: `business.*` → `BusinessLayout`, `platform.*` → `AdminLayout`
 
-3. **Tenant-prefixed routes** - If `/t/:slug/` block exists, add routes there too
+3. **Create pages using SmartStack components** (reference: `templates-frontend.md`)
+   - **List pages**: Use `SmartTable` (NOT HTML `<table>`), `SmartFilter`, `EntityCard` for grid view
+   - **Detail pages**: Use `EntityDetailCard`, `StatusBadge`, tab layout
+   - **Create/Edit pages**: Use `SmartForm` with `FluentValidation`-backed fields, tab layout
+   - **Dashboard pages**: Use `StatCard`, Recharts components
+   - Match wireframes from feature.json `specification.uiWireframes[]`
+
+4. **Create preferences hook**: `use{Module}Preferences.ts`
+   - pageSize, sortColumn, sortDirection, visibleColumns, viewMode, filters
+
+5. **Generate i18n** (4 languages: fr, en, it, de)
+   - All UI labels, validation messages, button text, empty states
+
+6. **Post-generation validation (BLOCKING)**:
+   - `npm run typecheck` MUST pass
+   - NO hardcoded colors (scan for `bg-blue-`, `text-gray-`, etc.)
+   - CSS variables ONLY: `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`
+   - Routes are NESTED and INSIDE Layout wrapper
+   - All pages have loading/error/empty states
+   - API client uses `@/services/api/apiClient` (NOT `import axios`)
+   - `EntityCard` for grid views (NOT custom `<div>` cards)
+
+**FORBIDDEN patterns (any of these = FAIL the task):**
+```
+import axios from 'axios'                    → use @/services/api/apiClient
+<table>...</table>                           → use SmartTable component
+<div className="bg-blue-600">               → use bg-[var(--color-accent-600)]
+<Route path="/business/app/mod" />           → MUST be nested inside BusinessLayout
+Only fr/en translations                      → MUST have 4 languages (fr, en, it, de)
+```
 
-4. **See `/application` skill templates-frontend.md** for full template patterns
+**Layout wrapper mapping:**
+| Context | Layout | Route path |
+|---------|--------|------------|
+| `platform.*` | `AdminLayout` | `/platform` |
+| `business.*` | `BusinessLayout` | `/business` |
+| `personal.*` | `UserLayout` | `/personal/myspace` |
 
 **API/Controller task guidance (MANDATORY folder hierarchy):**
 

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

@@ -6,6 +6,11 @@ next_step: steps/step-04-check.md
 
 # Step 3: Commit Changes
 
+> **CONTEXT OPTIMIZATION:** This file is only read ONCE (first iteration).
+> After the first full iteration, ALL subsequent iterations use the COMPACT LOOP
+> in step-04-check.md section 5 which includes inline commit logic.
+> **DO NOT re-read this file for iterations > 1.**
+
 ## YOUR TASK:
 
 Commit the changes from the executed task, finalize task tracking in prd.json, and append to history.
@@ -14,6 +19,83 @@ Commit the changes from the executed task, finalize task tracking in prd.json, a
 
 ## EXECUTION SEQUENCE:
 
+### 0. PRE-COMMIT VALIDATION (BLOCKING)
+
+**CRITICAL: Before ANY commit, verify all tests pass.**
+
+```bash
+# Check if test project exists
+PROJECT_NAME=$(basename $(pwd))
+TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
+
+if [ -d "$TEST_PROJECT" ]; then
+  echo "Running full test suite before commit..."
+
+  # Run ALL tests (not just current task's tests)
+  dotnet test "$TEST_PROJECT" --no-build --verbosity minimal
+
+  TEST_EXIT_CODE=$?
+
+  if [ $TEST_EXIT_CODE -ne 0 ]; then
+    echo "╔════════════════════════════════════════════════════════════╗"
+    echo "║  ❌ COMMIT BLOCKED: TESTS FAILED                         ║"
+    echo "╠════════════════════════════════════════════════════════════╣"
+    echo "║  Cannot commit code when tests are failing.               ║"
+    echo "║  This prevents broken code from entering the repository.  ║"
+    echo "╠════════════════════════════════════════════════════════════╣"
+    echo "║  ACTION REQUIRED:                                          ║"
+    echo "║  1. Review test failures above                             ║"
+    echo "║  2. Fix the failing code                                   ║"
+    echo "║  3. Re-run: dotnet test                                    ║"
+    echo "║  4. Once tests pass, Ralph will commit automatically       ║"
+    echo "╚════════════════════════════════════════════════════════════╝"
+
+    # Mark task as failed (do not complete)
+    # Update prd.json
+    const prd = readJSON('.ralph/prd.json');
+    const task = prd.tasks.find(t => t.id === {current_task_id});
+    task.status = 'failed';
+    task.error = 'Pre-commit test suite failed. Cannot commit broken code.';
+    writeJSON('.ralph/prd.json', prd);
+
+    # STOP - return to step-02 to fix
+    exit 1;
+  fi
+
+  echo "✅ All tests passed. Proceeding with commit..."
+fi
+```
+
+**Additional validation for specific categories:**
+
+```javascript
+const task = prd.tasks.find(t => t.id === {current_task_id});
+
+// For backend changes: ensure build succeeds
+if (['domain', 'application', 'infrastructure', 'api'].includes(task.category)) {
+  dotnet build --no-restore --verbosity quiet
+  if ($? !== 0) {
+    echo "❌ Build failed. Cannot commit broken code.";
+    task.status = 'failed';
+    task.error = 'Build failed';
+    exit 1;
+  }
+}
+
+// For frontend changes: ensure typecheck passes
+if (task.category === 'frontend') {
+  npm run typecheck
+  if ($? !== 0) {
+    echo "❌ TypeScript errors. Cannot commit broken code.";
+    task.status = 'failed';
+    task.error = 'TypeScript compilation failed';
+    exit 1;
+  }
+}
+```
+
+**If ALL validations pass, proceed to staging.**
+
 ### 1. Stage Changes
 
 **Add modified files:**