@atlashub/smartstack-cli 3.0.0 → 3.1.0

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

@@ -109,22 +109,27 @@ The loop only stops when this exact tag is output or max iterations reached.
 
 <workflow>
 **Standard flow (single module):**
-1. Parse flags and task description
-2. Verify MCP servers are available (MANDATORY)
-3. Initialize .ralph/ structure and state files
-4. Load current task from prd.json (or create initial task breakdown with categories, dependencies, and acceptance criteria)
-5. Execute ONE task per iteration
-6. Commit changes, update progress
-7. Check completion criteria
-8. If complete: generate final report
+1. Parse flags and task description (step-00)
+2. Verify MCP servers are available (step-00, MANDATORY)
+3. Initialize .ralph/ structure and state files (step-00)
+4. Load current task from prd.json — create task breakdown if new (step-01, READ ONCE)
+5. Execute first task (step-02, READ ONCE)
+6. Commit changes, update progress (step-03, READ ONCE)
+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
+   - 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
 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 (standard loop: steps 01→02→03→04)
-7. When module complete: advance to next module in queue
-8. Repeat steps 5-7 for each module
+6. Execute all tasks for current module via COMPACT LOOP
+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
 </workflow>
 
@@ -279,12 +284,14 @@ Before ANY work, verify MCP servers:
 
 <execution_rules>
 
-- **Load one step at a time** - Only load the current step file
-- **VERIFY MCP FIRST** - Never skip MCP validation
-- **ONE TASK PER ITERATION** - Don't batch tasks
-- **COMMIT AFTER EACH TASK** - Atomic progress
+- **Load step files ONCE** - Step files are read only on FIRST iteration. After that, use the COMPACT LOOP in step-04 section 5.
+- **VERIFY MCP FIRST** - Never skip MCP validation at init
+- **BATCH same-category tasks** - Execute up to 5 tasks of the same category per iteration (reduces loop iterations from 30+ to ~8)
+- **COMMIT AFTER EACH BATCH** - One commit per batch, not per individual task
 - **UPDATE progress.txt** - Persist learnings
 - **NEVER fake completion** - Only output promise when truly done
+- **NEVER STOP THE LOOP** - The loop is AUTONOMOUS. DO NOT pause between iterations. DO NOT wait for user input. Only stop on: completion, max iterations, dead-end, or explicit user interruption. Stopping for any other reason wastes context and causes re-reads.
+- **COMPACT OUTPUT** - During loop iterations, use 1-2 lines per task. Save verbose output for the final report.
 </execution_rules>
 
 <success_criteria>

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

@@ -6,6 +6,12 @@ next_step: steps/step-02-execute.md
 
 # Step 1: Load Task
 
+> **CONTEXT OPTIMIZATION:** This file is only read ONCE (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.
+
 ## YOUR TASK:
 
 Load the current task from prd.json or create initial task breakdown with categories, dependencies, and acceptance criteria.
@@ -76,23 +82,37 @@ function transformPrdJsonToRalphV2(prdJson, moduleCode) {
   const filesToCreate = prdJson.implementation?.filesToCreate || {};
 
   // 1. Generate tasks from implementation.filesToCreate (primary source)
+  //    CRITICAL: Frontend and i18n tasks are CONSOLIDATED into ONE module-level task each.
+  //    These use MCP scaffolding tools, NOT manual file-by-file generation.
   const lastIdByCategory = {};
+  const frontendFiles = [];  // Collect frontend files for consolidated task
+  const i18nFiles = [];      // Collect i18n files for consolidated task
 
   for (const layer of layerOrder) {
     const files = filesToCreate[layer.key] || [];
+
+    // FRONTEND & I18N: Collect files, do NOT create individual tasks
+    if (layer.category === "frontend") {
+      frontendFiles.push(...files);
+      continue;  // Skip individual task creation
+    }
+
     for (const fileSpec of files) {
+      // Check if this is an i18n file (category "infrastructure" but path contains i18n)
+      if (fileSpec.path?.includes('i18n/') || fileSpec.path?.includes('/locales/')) {
+        i18nFiles.push(fileSpec);
+        continue;  // Skip individual task creation
+      }
+
       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
+      // Cross-layer: api depends on last application 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"]);
       }
@@ -131,6 +151,71 @@ function transformPrdJsonToRalphV2(prdJson, moduleCode) {
     }
   }
 
+  // 1b. Create CONSOLIDATED frontend task (ONE task per module, uses MCP tools)
+  if (frontendFiles.length > 0) {
+    const apiDepId = lastIdByCategory["api"] || lastIdByCategory["application"];
+    const allLinkedUCs = [...new Set(frontendFiles.flatMap(f => f.linkedUCs || []))];
+    const allLinkedWireframes = [...new Set(frontendFiles.flatMap(f => f.linkedWireframes || []))];
+    const allPaths = frontendFiles.map(f => f.path);
+
+    tasks.push({
+      id: taskId,
+      description: `[frontend] Generate COMPLETE frontend for module ${moduleCode} via MCP scaffold tools (${frontendFiles.length} files: pages, components, hooks, API client)`,
+      status: "pending",
+      category: "frontend",
+      dependencies: apiDepId ? [apiDepId] : [],
+      acceptance_criteria: [
+        "MCP scaffold_api_client called → API client + types generated",
+        "MCP scaffold_routes called → routes.tsx updated with nested routes inside Layout wrapper",
+        "Pages match wireframes: " + allLinkedWireframes.join(", "),
+        "SmartTable for lists (NOT HTML tables), EntityCard for grids (NOT custom divs)",
+        "CSS variables ONLY (NO hardcoded Tailwind colors like bg-blue-600)",
+        "useNavigate + useParams for routing, NOT window.location",
+        "Loading/error/empty states on all pages",
+        "4-language i18n keys (fr, en, it, de)",
+        "npm run typecheck passes"
+      ].join("; "),
+      started_at: null,
+      completed_at: null,
+      iteration: null,
+      commit_hash: null,
+      files_changed: { created: allPaths, modified: [] },
+      validation: null,
+      error: null,
+      module: moduleCode,
+      _frontendMeta: {
+        wireframes: allLinkedWireframes,
+        linkedUCs: allLinkedUCs,
+        filesToCreate: frontendFiles
+      }
+    });
+
+    lastIdByCategory["frontend"] = taskId;
+    taskId++;
+  }
+
+  // 1c. Create CONSOLIDATED i18n task (ONE task per module)
+  if (i18nFiles.length > 0) {
+    tasks.push({
+      id: taskId,
+      description: `[i18n] Generate i18n translations for module ${moduleCode} (4 languages: fr, en, it, de)`,
+      status: "pending",
+      category: "i18n",
+      dependencies: lastIdByCategory["frontend"] ? [lastIdByCategory["frontend"]] : [],
+      acceptance_criteria: "4 JSON files (fr, en, it, de) with identical keys; all UI labels translated",
+      started_at: null,
+      completed_at: null,
+      iteration: null,
+      commit_hash: null,
+      files_changed: { created: i18nFiles.map(f => f.path), modified: [] },
+      validation: null,
+      error: null,
+      module: moduleCode
+    });
+    lastIdByCategory["i18n"] = taskId;
+    taskId++;
+  }
+
   // 2. Add IClientSeedDataProvider task for client projects (ExtensionsDbContext)
   // This is MANDATORY - without it, core seed data (navigation, permissions, roles) is dead code
   const hasClientSeedData = filesToCreate["seedData"]?.some(f =>

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):**