@atlashub/smartstack-cli 2.9.0 → 3.1.0

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:**
@@ -44,7 +126,7 @@ 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>
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 EOF
 )"
 ```
@@ -189,7 +271,7 @@ Iteration {current_iteration} complete
 Status: {task.status}
 {current_module ? "Module: " + current_module : ""}
 
-Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 EOF
 )"
 ```

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

@@ -34,6 +34,97 @@ const hasBlocked   = tasksBlocked > 0;
 const hasPending   = tasksPending > 0;
 ```
 
+### 1.5. REGRESSION CHECK (MANDATORY AFTER EACH ITERATION)
+
+**CRITICAL: After EVERY task completion, run full test suite to detect regressions.**
+
+```bash
+PROJECT_NAME=$(basename $(pwd))
+TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
+
+if [ -d "$TEST_PROJECT" ]; then
+  echo "🔍 Running regression check (full test suite)..."
+
+  # Run ALL tests to ensure nothing broke
+  dotnet test "$TEST_PROJECT" --no-build --verbosity minimal --logger "console;verbosity=minimal"
+
+  REGRESSION_EXIT_CODE=$?
+
+  if [ $REGRESSION_EXIT_CODE -ne 0 ]; then
+    echo "╔════════════════════════════════════════════════════════════╗"
+    echo "║  ⚠️  REGRESSION DETECTED                                  ║"
+    echo "╠════════════════════════════════════════════════════════════╣"
+    echo "║  A previously passing test is now failing.                 ║"
+    echo "║  This indicates the last change broke existing code.       ║"
+    echo "╠════════════════════════════════════════════════════════════╣"
+    echo "║  CORRECTIVE ACTION:                                        ║"
+    echo "║  1. Identify which test(s) started failing                 ║"
+    echo "║  2. Analyze what changed in last commit                    ║"
+    echo "║  3. Fix the regression                                     ║"
+    echo "║  4. Commit the fix                                         ║"
+    echo "║  5. Ralph will continue automatically                      ║"
+    echo "╚════════════════════════════════════════════════════════════╝"
+
+    // Parse test output to identify which tests failed
+    const regressionTests = parseFailedTests(testOutput);
+
+    // Log regression details to progress.txt
+    const progressEntry = `
+[REGRESSION DETECTED - Iteration ${prd.config.current_iteration}]
+Failed tests: ${regressionTests.join(', ')}
+Last completed task: ${prd.tasks.find(t => t.id === lastCompletedTaskId).description}
+Commit: ${lastCommitHash}
+
+ACTION REQUIRED: Fix regression before continuing.
+`;
+    appendToFile('.ralph/progress.txt', progressEntry);
+
+    // Mark current state as having regression
+    prd.regression_detected = {
+      iteration: prd.config.current_iteration,
+      failed_tests: regressionTests,
+      last_task: lastCompletedTaskId,
+      commit_hash: lastCommitHash
+    };
+    writeJSON('.ralph/prd.json', prd);
+
+    // Create a new task to fix the regression
+    const fixTask = {
+      id: prd.tasks.length + 1,
+      description: `Fix regression: ${regressionTests.length} test(s) failing`,
+      status: 'pending',
+      category: 'validation',
+      dependencies: [],
+      acceptance_criteria: `All tests pass: ${regressionTests.join(', ')}`,
+      started_at: null,
+      completed_at: null,
+      iteration: null,
+      commit_hash: null,
+      files_changed: { created: [], modified: [] },
+      validation: null,
+      error: null
+    };
+    prd.tasks.push(fixTask);
+    prd.updated_at = new Date().toISOString();
+    writeJSON('.ralph/prd.json', prd);
+
+    // DO NOT STOP - continue to next task (which is the fix task)
+    echo "📋 Created task ${fixTask.id}: Fix regression";
+  } else {
+    echo "✅ Regression check passed. No tests broken.";
+
+    // Update test metrics in progress.txt
+    const testStats = parseTestStats(testOutput);
+    const metricsEntry = `
+[Test Metrics - Iteration ${prd.config.current_iteration}]
+Total: ${testStats.total} | Passed: ${testStats.passed} | Failed: ${testStats.failed} | Skipped: ${testStats.skipped}
+Duration: ${testStats.duration}
+`;
+    appendToFile('.ralph/progress.txt', metricsEntry);
+  }
+fi
+```
+
 ### 2. Check Iteration Limit
 
 **If `prd.config.current_iteration` > `prd.config.max_iterations`:**
@@ -191,20 +282,148 @@ writeJSON('.ralph/prd.json', prd);
 
 **Proceed to step-05-report.md**
 
-### 5. More Tasks Remaining
+### 5. More Tasks Remaining — COMPACT LOOP (CRITICAL)
+
+> **MANDATORY RULE: DO NOT STOP. DO NOT WAIT FOR USER INPUT. DO NOT RE-READ STEP FILES.**
+> After the first full iteration (step-01 → step-02 → step-03 → step-04), all subsequent iterations
+> MUST use this COMPACT LOOP inline. Re-reading step files wastes context and causes the loop to stall.
+> **STOPPING THE LOOP = BUG.** Only completion, max iterations, or dead-end stop the loop.
 
 **If hasPending AND iteration < max_iterations:**
 
+Display compact progress (ONE line):
 ```
-Progress: {tasksCompleted} / {tasksTotal} tasks
-Failed: {tasksFailed}  |  Blocked: {tasksBlocked}  |  Pending: {tasksPending}
+[{current_iteration}/{max_iterations}] {tasksCompleted}/{tasksTotal} done | Next: finding eligible task...
+```
+
+**IMMEDIATELY execute the following inline loop — DO NOT re-read step files:**
 
-Next eligible task will be determined by dependency resolution.
+#### 5a. Find Next Eligible Task (inline step-01)
 
-Continuing to next iteration...
+```javascript
+const prd = readJSON('.ralph/prd.json');
+
+// Block tasks whose dependencies failed
+for (const task of prd.tasks) {
+  if (task.status !== 'pending') continue;
+  const depsBlocked = task.dependencies.some(depId => {
+    const dep = prd.tasks.find(t => t.id === depId);
+    return dep && (dep.status === 'failed' || dep.status === 'blocked');
+  });
+  if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
+}
+
+// Find ALL eligible tasks (dependencies met)
+const eligible = prd.tasks.filter(task => {
+  if (task.status !== 'pending') return false;
+  return task.dependencies.every(depId => {
+    const dep = prd.tasks.find(t => t.id === depId);
+    return dep && dep.status === 'completed';
+  });
+});
+
+if (eligible.length === 0) {
+  // Dead-end or all done — re-run sections 2-4 above
+  goto CHECK_COMPLETION;
+}
+
+// BATCH MODE: group eligible tasks by category, take the first group
+const firstCategory = eligible[0].category;
+const batch = eligible.filter(t => t.category === firstCategory);
+// Cap batch at 5 tasks max to keep atomic
+const tasksToExecute = batch.slice(0, 5);
 ```
 
-**Loop back to step-01-task.md**
+Display:
+```
+Batch: {tasksToExecute.length} task(s) [{firstCategory}]
+  {tasksToExecute.map(t => `[${t.id}] ${t.description}`).join('\n  ')}
+```
+
+#### 5b. Execute Batch (inline step-02)
+
+**For EACH task in tasksToExecute:**
+
+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
+
+**CATEGORY-SPECIFIC EXECUTION RULES:**
+
+**IF category = "frontend":** Follow MCP-FIRST protocol (MANDATORY):
+  1. Call `mcp__smartstack__scaffold_api_client` → generates API client + types
+  2. Call `mcp__smartstack__scaffold_routes` → updates routes inside Layout wrapper
+  3. Create pages using SmartStack components (SmartTable, EntityCard, SmartForm, SmartFilter)
+  4. CSS variables ONLY (NO `bg-blue-600`, use `bg-[var(--color-accent-600)]`)
+  5. `EntityCard` for grids, `SmartTable` for lists (NO HTML `<table>` or custom `<div>` cards)
+  6. All pages MUST have loading/error/empty states
+  7. API client uses `@/services/api/apiClient` (NOT axios)
+  8. Generate 4-language i18n (fr, en, it, de)
+  9. `npm run typecheck` MUST pass
+
+**IF category = "infrastructure":** Seed data in `Infrastructure/Persistence/Seeding/Data/{Module}/`
+
+**IF category = "api":** Controllers in `Api/Controllers/{Context}/{App}/{Entity}Controller.cs`
+
+After ALL tasks in batch executed:
+- Run `mcp__smartstack__validate_conventions` ONCE for the whole batch
+- Quick build check: `dotnet build --no-restore` (backend) or `npm run typecheck` (frontend)
+
+#### 5c. Commit Batch (inline step-03)
+
+```bash
+# Stage all changed files
+git add {all files from batch}
+git add .ralph/prd.json
+
+# Single commit for the batch
+git commit -m "$(cat <<'EOF'
+feat({scope}): [{firstCategory}] {tasksToExecute.length} tasks — {short summary}
+
+Tasks: {tasksToExecute.map(t => t.id).join(', ')} / {tasks_total}
+Iteration: {current_iteration}
+{current_module ? "Module: " + current_module : ""}
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+
+COMMIT_HASH=$(git rev-parse --short HEAD)
+```
+
+**Finalize each task in prd.json:**
+```javascript
+for (const task of tasksToExecute) {
+  if (task.status !== 'failed') task.status = 'completed';
+  task.completed_at = now;
+  task.iteration = prd.config.current_iteration;
+  task.commit_hash = COMMIT_HASH;
+}
+prd.history.push({
+  iteration: prd.config.current_iteration,
+  task_ids: tasksToExecute.map(t => t.id),
+  action: 'batch-completed',
+  timestamp: now,
+  commit_hash: COMMIT_HASH,
+  notes: "{What was accomplished}"
+});
+prd.config.current_iteration++;
+prd.updated_at = now;
+writeJSON('.ralph/prd.json', prd);
+```
+
+```bash
+git add .ralph/prd.json .ralph/progress.txt
+[ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
+git commit -m "chore(ralph): progress — iteration {current_iteration}"
+```
+
+#### 5d. Re-check Completion (loop back to section 1)
+
+**IMMEDIATELY go back to section 1 (Read Current State) of THIS step.**
+**DO NOT stop. DO NOT wait for user. DO NOT re-read step files.**
 
 ---
 
@@ -300,6 +519,16 @@ Completion Check:
 
 **Always update `prd.status` and `prd.updated_at` before proceeding.**
 
+**LOOP CONTINUATION IS MANDATORY:**
+- After the first full iteration (step-01→02→03→04), ALL subsequent iterations use the COMPACT LOOP in section 5.
+- DO NOT re-read step-01, step-02, step-03 files. You already know the instructions.
+- DO NOT stop and wait for user input between iterations.
+- DO NOT output a summary and pause. The loop is AUTONOMOUS.
+- The ONLY reasons to stop: completion, max iterations, dead-end, or user interruption.
+- Stopping for any other reason is a **BUG** that wastes user time and context.
+- **BATCH tasks of the same category** to reduce iterations (max 5 per batch).
+- Prefer compact output (1-2 lines per task) over verbose output during the loop.
+
 ---
 
 ## NEXT STEP:

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

@@ -123,6 +123,86 @@ if (hasQueue) {
 }
 ```
 
+### 1c. Extract Test Metrics (from progress.txt and test execution)
+
+**CRITICAL: Test metrics MUST be included in the final report.**
+
+```bash
+PROJECT_NAME=$(basename $(pwd))
+TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
+
+testMetrics={
+  projectExists: false,
+  testsExecuted: false,
+  lastRunStatus: "unknown",
+  totalTests: 0,
+  passed: 0,
+  failed: 0,
+  skipped: 0,
+  coverage: 0,
+  duration: 0
+};
+
+if [ -d "$TEST_PROJECT" ]; then
+  testMetrics.projectExists = true;
+
+  # Extract latest test metrics from progress.txt
+  if [ -f ".ralph/progress.txt" ]; then
+    # Parse last "Test Metrics" entry
+    LAST_METRICS=$(grep -A 3 "\[Test Metrics" .ralph/progress.txt | tail -4)
+
+    # Extract values using regex
+    TOTAL=$(echo "$LAST_METRICS" | grep -oP "Total: \K\d+")
+    PASSED=$(echo "$LAST_METRICS" | grep -oP "Passed: \K\d+")
+    FAILED=$(echo "$LAST_METRICS" | grep -oP "Failed: \K\d+")
+    SKIPPED=$(echo "$LAST_METRICS" | grep -oP "Skipped: \K\d+")
+    DURATION=$(echo "$LAST_METRICS" | grep -oP "Duration: \K[\d\.]+")
+
+    if [ -n "$TOTAL" ]; then
+      testMetrics.testsExecuted = true;
+      testMetrics.totalTests = $TOTAL;
+      testMetrics.passed = $PASSED;
+      testMetrics.failed = $FAILED;
+      testMetrics.skipped = $SKIPPED;
+      testMetrics.duration = $DURATION;
+      testMetrics.lastRunStatus = [ $FAILED -eq 0 ] ? "passed" : "failed";
+    fi
+  fi
+
+  # If no metrics in progress.txt, run tests now to get final stats
+  if [ "$testMetrics.testsExecuted" = false ]; then
+    echo "Running final test suite to collect metrics...";
+    TEST_OUTPUT=$(dotnet test "$TEST_PROJECT" --no-build --verbosity minimal 2>&1);
+    TEST_EXIT_CODE=$?;
+
+    testMetrics.testsExecuted = true;
+    testMetrics.lastRunStatus = [ $TEST_EXIT_CODE -eq 0 ] ? "passed" : "failed";
+
+    # Parse test output
+    testMetrics.totalTests = parseTestCount(TEST_OUTPUT);
+    testMetrics.passed = parsePassedCount(TEST_OUTPUT);
+    testMetrics.failed = parseFailedCount(TEST_OUTPUT);
+    testMetrics.skipped = parseSkippedCount(TEST_OUTPUT);
+    testMetrics.duration = parseDuration(TEST_OUTPUT);
+  fi
+
+  # Get coverage using MCP
+  const coverageResult = mcp__smartstack__analyze_test_coverage({
+    project_path: process.cwd()
+  });
+
+  if (coverageResult && coverageResult.percentage) {
+    testMetrics.coverage = coverageResult.percentage;
+  }
+fi
+```
+
+**Store metrics for report generation:**
+
+```javascript
+stats.tests = testMetrics;
+```
+
 ### 2. Collect MCP Usage (from logs if available)
 
 **Parse from verbose logs:**
@@ -187,6 +267,41 @@ const validationStats = {
 **Modules: {moduleStats.completedModules}/{moduleStats.totalModules} completed**
 {end if}
 
+## Test Metrics
+
+{if testMetrics.projectExists:}
+| Metric | Value |
+|--------|-------|
+| **Test Project** | ✅ `{TEST_PROJECT}` |
+| **Tests Executed** | {testMetrics.testsExecuted ? '✅ Yes' : '❌ No'} |
+| **Last Run Status** | {testMetrics.lastRunStatus === 'passed' ? '✅ PASSED' : testMetrics.lastRunStatus === 'failed' ? '❌ FAILED' : '⚠️ UNKNOWN'} |
+| **Total Tests** | {testMetrics.totalTests} |
+| **Passed** | ✅ {testMetrics.passed} |
+| **Failed** | ❌ {testMetrics.failed} |
+| **Skipped** | ⏭️ {testMetrics.skipped} |
+| **Coverage** | {testMetrics.coverage}% {testMetrics.coverage >= 80 ? '✅' : testMetrics.coverage >= 60 ? '⚠️' : '❌'} |
+| **Duration** | {testMetrics.duration}s |
+
+{if testMetrics.failed > 0:}
+⚠️ **WARNING:** Some tests are failing. The module is NOT production-ready.
+{end if}
+
+{if testMetrics.coverage < 80:}
+⚠️ **WARNING:** Test coverage is below 80% minimum. Consider adding more tests.
+{end if}
+
+{else:}
+❌ **No test project found.** Tests were not created for this module.
+
+**RECOMMENDATION:** Create a test project and add comprehensive tests before deploying to production.
+
+Suggested command:
+```bash
+dotnet new xunit -n {PROJECT_NAME}.Tests.Unit -o tests/{PROJECT_NAME}.Tests.Unit
+dotnet sln add tests/{PROJECT_NAME}.Tests.Unit
+```
+{end if}
+
 ## Failed Tasks
 
 {if any failed tasks:}

package/templates/skills/validate-feature/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: validate-feature
+description: Validate that a scaffolded feature works end-to-end (compile, test, API smoke test)
+version: 1.0.0
+author: SmartStack
+tags: [testing, validation, smoke-test, integration]
+---
+
+# /validate-feature
+
+## PURPOSE
+
+Validates that a scaffolded SmartStack feature **actually works** by running:
+1. Compilation check (`dotnet build`)
+2. Unit tests (`dotnet test`)
+3. Integration tests (`dotnet test --filter`)
+4. API smoke test (start API, hit CRUD endpoints, verify responses)
+
+## WHEN TO USE
+
+- After running `/application` to scaffold a new feature
+- After making changes to backend code (controllers, services, entities)
+- Before committing to verify nothing is broken
+- As a confidence check that the full stack works
+
+## USAGE
+
+```
+/validate-feature {EntityName}
+```
+
+**Examples:**
+```
+/validate-feature Product
+/validate-feature Order
+/validate-feature UserProfile
+```
+
+## PARAMETERS
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `{entity_name}` | YES | PascalCase entity name to validate |
+
+## PREREQUISITES
+
+- The solution must compile
+- Test project must exist with infrastructure (SmartStackTestFactory, IntegrationTestBase)
+- Entity must have been scaffolded (controller, service, entity files exist)
+
+## EXECUTION
+
+This skill follows a 4-step sequential workflow:
+
+| Step | File | Description | Blocking |
+|------|------|-------------|----------|
+| 1 | `steps/step-01-compile.md` | Build the full solution | YES |
+| 2 | `steps/step-02-unit-tests.md` | Run unit tests | YES |
+| 3 | `steps/step-03-integration-tests.md` | Run integration tests | YES |
+| 4 | `steps/step-04-api-smoke.md` | Start API and test CRUD endpoints | YES |
+
+Each step must PASS before proceeding to the next.
+
+## OUTPUT
+
+A validation report showing pass/fail for each check:
+
+```
+## Feature Validation: {EntityName}
+
+| Check | Result |
+|-------|--------|
+| Solution build | PASS |
+| Unit tests (X passed) | PASS |
+| Integration tests (X passed) | PASS |
+| API smoke: GET /api/{entity} | PASS (200) |
+| API smoke: POST /api/{entity} | PASS (201) |
+| API smoke: GET /api/{entity}/{id} | PASS (200) |
+| API smoke: PUT /api/{entity}/{id} | PASS (200) |
+| API smoke: DELETE /api/{entity}/{id} | PASS (204) |
+
+Result: ALL CHECKS PASSED
+```

package/templates/skills/validate-feature/steps/step-01-compile.md

@@ -0,0 +1,38 @@
+---
+name: step-01-compile
+description: Build the full solution to verify compilation
+next_step: steps/step-02-unit-tests.md
+---
+
+# Step 1: Compilation Check
+
+## BLOCKING - Must pass before proceeding
+
+### 1. Locate the solution file
+
+```bash
+# Find the .sln file
+ls *.sln 2>/dev/null || find . -maxdepth 2 -name "*.sln" -type f
+```
+
+### 2. Build the entire solution
+
+```bash
+dotnet build {SolutionFile} --verbosity minimal
+```
+
+### 3. Evaluate result
+
+- **Build succeeded** -> Proceed to step 2
+- **Build failed** -> Read the error output, identify the issue:
+  - Missing using statement -> Add it
+  - Type not found -> Check project references
+  - Method signature mismatch -> Fix the code
+  - **Re-build until it succeeds**
+
+### 4. Store state
+
+```
+{solution_file} = path to .sln file
+{build_result} = PASS or FAIL
+```

package/templates/skills/validate-feature/steps/step-02-unit-tests.md

@@ -0,0 +1,45 @@
+---
+name: step-02-unit-tests
+description: Run unit tests to verify business logic
+prev_step: steps/step-01-compile.md
+next_step: steps/step-03-integration-tests.md
+---
+
+# Step 2: Unit Tests
+
+## BLOCKING - All unit tests must pass
+
+### 1. Locate the test project
+
+```bash
+# Find test project
+ls tests/*/*.csproj 2>/dev/null || ls *Tests*/*.csproj 2>/dev/null
+```
+
+### 2. Run unit tests only
+
+```bash
+dotnet test {TestProject} --no-build --filter "FullyQualifiedName~Unit" --verbosity normal
+```
+
+If the filter doesn't match, try:
+
+```bash
+dotnet test {TestProject} --no-build --filter "Category!=Integration" --verbosity normal
+```
+
+### 3. Evaluate result
+
+- **All tests passed** -> Proceed to step 3
+- **Tests failed** -> Read the failure output:
+  - Assertion failure -> Check if the test expectation matches the implementation
+  - Exception thrown -> Check if the service/entity code is correct
+  - Compilation error -> Should not happen (step 1 passed), but fix if it does
+  - **Fix and re-run until all pass**
+
+### 4. Store state
+
+```
+{unit_test_count} = number of tests that passed
+{unit_test_result} = PASS or FAIL
+```