@atlashub/smartstack-cli 1.35.0 → 1.37.0

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

@@ -1,6 +1,6 @@
 ---
 name: step-02-execute
-description: Execute ONE task from the task list
+description: Execute ONE task with dependency checks and rich tracking
 next_step: steps/step-03-commit.md
 ---
 
@@ -20,21 +20,68 @@ Execute exactly ONE task from prd.json. Do NOT batch multiple tasks.
 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
 
 ---
 
 ## EXECUTION SEQUENCE:
 
-### 1. Understand the Task
+### 1. Verify Dependencies
+
+**BEFORE starting, check all dependencies are satisfied:**
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const task = prd.tasks.find(t => t.id === {current_task_id});
+
+for (const depId of task.dependencies) {
+  const dep = prd.tasks.find(t => t.id === depId);
+  if (!dep || dep.status !== 'completed') {
+    echo `❌ BLOCKED: Task ${task.id} depends on task ${depId} (status: ${dep?.status || 'missing'})`;
+    task.status = 'blocked';
+    task.error = `Dependency task ${depId} not completed (${dep?.status})`;
+    writeJSON('.ralph/prd.json', prd);
+    STOP - return to step-01 to find next eligible task
+  }
+}
+```
+
+### 2. Mark Task as In-Progress
+
+**Update prd.json immediately:**
+
+```javascript
+task.status = 'in_progress';
+task.started_at = new Date().toISOString();
+prd.updated_at = task.started_at;
+writeJSON('.ralph/prd.json', prd);
+```
+
+### 3. Understand the Task
 
 **ULTRA THINK:**
 
 - What exactly needs to be done?
 - What files need to be created/modified?
-- What are the success criteria?
+- What are the acceptance criteria? → `{current_task_criteria}`
 - What patterns should be followed?
+- What category is this? → `{current_task_category}`
+
+**Category-specific guidance:**
 
-### 2. Explore Context (if needed)
+| Category | MCP Tools | Patterns |
+|----------|-----------|----------|
+| `domain` | `validate_conventions` | Entity base class, IHasData, audit fields |
+| `application` | `validate_conventions`, `scaffold_extension` | CQRS, MediatR, FluentValidation |
+| `infrastructure` | `check_migrations`, `suggest_migration` | EF Core config, HasData seeding |
+| `api` | `scaffold_routes`, `validate_security` | Controller conventions, authorization |
+| `frontend` | `validate_frontend_routes`, `scaffold_frontend_extension` | React patterns, hooks |
+| `i18n` | - | 4-language JSON structure |
+| `test` | `scaffold_tests`, `analyze_test_coverage` | xUnit, test naming conventions |
+| `validation` | `validate_conventions` | Build, test, lint checks |
+
+### 4. Explore Context (if needed)
 
 **Use subagents sparingly:**
 
@@ -50,7 +97,7 @@ If exploration needed:
 - Grep for code search
 - Read for file contents
 
-### 3. Execute Implementation
+### 5. Execute Implementation
 
 **Implement the task:**
 
@@ -60,6 +107,13 @@ If exploration needed:
 - Add appropriate logging
 - Handle errors properly
 
+**Track every file operation:**
+
+```
+{files_created}  = []   // Accumulate as you create files
+{files_modified} = []   // Accumulate as you modify files
+```
+
 **Use TodoWrite to track sub-steps:**
 
 ```
@@ -69,32 +123,68 @@ If task has multiple parts:
   3. Mark completed when done
 ```
 
-### 4. Validate with MCP
+### 6. Validate with MCP
 
-**After implementation, validate:**
+**After implementation, validate based on category:**
 
 ```
+# Always run general validation
 mcp__smartstack__validate_conventions:
   checks: ["all"]
+
+# Category-specific validation
+if category == "infrastructure":
+  mcp__smartstack__check_migrations
+
+if category == "api":
+  mcp__smartstack__validate_security
+
+if category == "frontend":
+  mcp__smartstack__validate_frontend_routes
+
+if category == "test":
+  mcp__smartstack__analyze_test_coverage
+```
+
+**Record validation result:**
+```
+{validation_result} = "passed" | "failed: {reason}"
 ```
 
 **If validation fails:**
 - Fix the issues
 - Re-validate
 - Do NOT proceed until valid
+- If cannot fix: set `{validation_result} = "failed: {reason}"`
+
+### 7. Check Acceptance Criteria
+
+**Verify against `{current_task_criteria}`:**
+
+```
+ULTRA THINK: Does the implementation satisfy the acceptance criteria?
+
+Criteria: {current_task_criteria}
+
+✅ Met / ❌ Not met (explain why)
+```
 
-### 5. Run Quick Tests
+**If criteria NOT met:**
+- Continue working until met
+- If impossible to meet: document in `{task_error}`
+
+### 8. Run Quick Tests
 
 **If applicable:**
 
 ```bash
-# For backend changes
-dotnet build src/SmartStack.Api/SmartStack.Api.csproj --no-restore
+# For backend changes (domain, application, infrastructure, api)
+dotnet build --no-restore 2>&1
 
 # For frontend changes
 npm run lint && npm run typecheck
 
-# For specific tests
+# For test category
 dotnet test --filter "FullyQualifiedName~{relevant_test}"
 ```
 
@@ -103,17 +193,33 @@ dotnet test --filter "FullyQualifiedName~{relevant_test}"
 - Re-run until passing
 - Document what was fixed
 
-### 6. Track Progress
+### 9. Update Task State in prd.json
 
-**Update internal state:**
+**Persist tracking data BEFORE committing:**
 
-```
-{files_created}  = ["path/to/file1.cs", "path/to/file2.ts"]
-{files_modified} = ["path/to/existing.cs"]
-{tests_run}      = true/false
-{validation}     = "passed" / "failed"
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const task = prd.tasks.find(t => t.id === {current_task_id});
+
+task.files_changed = {
+  created: {files_created},
+  modified: {files_modified}
+};
+task.validation = {validation_result};
+
+// If task failed
+if ({task_failed}) {
+  task.status = 'failed';
+  task.error = '{failure_reason}';
+  task.completed_at = new Date().toISOString();
+}
+
+prd.updated_at = new Date().toISOString();
+writeJSON('.ralph/prd.json', prd);
 ```
 
+**Note: `task.status` stays `"in_progress"` until step-03 confirms the commit. Only `"failed"` is set here if the task cannot be completed.**
+
 ---
 
 ## IMPORTANT CONSTRAINTS:
@@ -121,7 +227,9 @@ dotnet test --filter "FullyQualifiedName~{relevant_test}"
 ### What TO DO:
 - Implement exactly what the task describes
 - Follow existing patterns
-- Validate changes
+- Validate changes with MCP
+- Track all file operations
+- Check acceptance criteria
 - Write minimal, clean code
 
 ### What NOT TO DO:
@@ -129,6 +237,7 @@ dotnet test --filter "FullyQualifiedName~{relevant_test}"
 - Don't refactor unrelated code
 - Don't add "nice to have" features
 - Don't skip validation
+- Don't forget to track files
 
 ---
 
@@ -140,9 +249,11 @@ Task Executed:
 | Action | Details |
 |--------|---------|
 | Task | [{current_task_id}] {current_task_description} |
+| Category | {current_task_category} |
 | Files Created | {files_created} |
 | Files Modified | {files_modified} |
-| Validation | ✅ Passed |
+| Validation | {validation_result} |
+| Acceptance | ✅ Criteria met |
 | Tests | ✅ Passed |
 
 -> Committing changes...
@@ -154,10 +265,11 @@ Task Executed:
 
 **If task cannot be completed:**
 
-1. Document the blocker
-2. Update progress.txt with learnings
-3. Mark task with a note (don't mark passes: true)
-4. Proceed to step-03 to save progress
+1. Document the blocker in `task.error`
+2. Set `task.status = "failed"` in prd.json
+3. Update progress.txt with learnings
+4. Proceed to step-03 to save progress (commit what was done)
+5. step-04 will handle blocked downstream tasks
 
 **If build fails:**
 
@@ -166,6 +278,12 @@ Task Executed:
 3. Re-build until success
 4. Then proceed
 
+**If validation fails:**
+
+1. Fix validation issues
+2. Re-validate until clean
+3. If unfixable: document in `task.error`, set `task.validation = "failed: {reason}"`
+
 ---
 
 ## NEXT STEP:

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

@@ -1,6 +1,6 @@
 ---
 name: step-03-commit
-description: Commit changes, update prd.json and progress.txt
+description: Commit changes, update prd.json v2 with full tracking
 next_step: steps/step-04-check.md
 ---
 
@@ -8,7 +8,7 @@ next_step: steps/step-04-check.md
 
 ## YOUR TASK:
 
-Commit the changes from the executed task, update prd.json and progress.txt.
+Commit the changes from the executed task, finalize task tracking in prd.json, and append to history.
 
 ---
 
@@ -20,12 +20,16 @@ Commit the changes from the executed task, update prd.json and progress.txt.
 
 ```bash
 git add {files_created} {files_modified}
+
+# Also stage prd.json (already updated in step-02)
+git add .ralph/prd.json
 ```
 
 **Verify staged changes:**
 
 ```bash
 git status
+git diff --cached --stat
 ```
 
 ### 2. Create Commit
@@ -34,47 +38,107 @@ git status
 
 ```bash
 git commit -m "$(cat <<'EOF'
-feat(ralph): {current_task_description}
+{PREFIX}({scope}): {current_task_description}
 
 Task {current_task_id}/{tasks_total} - Iteration {current_iteration}
+Category: {current_task_category}
 
 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 EOF
 )"
 ```
 
-**Commit message format:**
-- Type: `feat`, `fix`, `refactor`, `test`, `docs`
-- Scope: `ralph` or specific module
-- Description: Task description
-- Footer: Iteration info
+**Determine commit prefix from category:**
+
+| Category | Prefix | Scope |
+|----------|--------|-------|
+| `domain` | `feat` | entity name or module |
+| `application` | `feat` | module name |
+| `infrastructure` | `db` | migrations / config |
+| `api` | `feat` | controller name |
+| `frontend` | `feat` | component/page name |
+| `i18n` | `chore` | i18n |
+| `test` | `test` | module name |
+| `validation` | `chore` | validation |
+| `other` | `chore` | ralph |
+
+**Get commit hash:**
+```bash
+COMMIT_HASH=$(git rev-parse --short HEAD)
+```
+
+### 3. Finalize Task in prd.json
 
-### 3. Update prd.json
+**Mark task as completed with all tracking data:**
 
-**Mark current task as complete:**
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const task = prd.tasks.find(t => t.id === {current_task_id});
+const now = new Date().toISOString();
 
-```json
-{
-  "feature": "{task_description}",
-  "current_iteration": {current_iteration + 1},
-  "tasks": [
-    { "id": 1, "description": "...", "passes": true },   // was false
-    { "id": 2, "description": "...", "passes": false }   // next task
-  ]
+// Only mark completed if not already failed in step-02
+if (task.status !== 'failed') {
+  task.status = 'completed';
+}
+task.completed_at = now;
+task.iteration = prd.config.current_iteration;
+task.commit_hash = COMMIT_HASH;
+
+// files_changed already set in step-02, but verify
+if (!task.files_changed || (!task.files_changed.created.length && !task.files_changed.modified.length)) {
+  // Fallback: extract from git diff
+  task.files_changed = {
+    created: getGitNewFiles(),    // git diff --cached --name-only --diff-filter=A
+    modified: getGitModifiedFiles() // git diff --cached --name-only --diff-filter=M
+  };
 }
 ```
 
-**Write updated prd.json:**
+### 4. Append to History
+
+**Add structured iteration entry:**
 
 ```javascript
-const prd = readJSON('.ralph/prd.json');
-const task = prd.tasks.find(t => t.id === currentTaskId);
-task.passes = true;
-prd.current_iteration++;
+prd.history.push({
+  iteration: prd.config.current_iteration,
+  task_id: task.id,
+  action: task.status,  // "completed" or "failed"
+  timestamp: now,
+  commit_hash: COMMIT_HASH,
+  duration_seconds: Math.round(
+    (new Date(now) - new Date(task.started_at)) / 1000
+  ),
+  notes: "{What was learned or accomplished during this task}"
+});
+```
+
+### 5. Increment Iteration and Update Timestamps
+
+**IMPORTANT: Increment AFTER recording the current iteration in task and history.**
+
+```javascript
+prd.config.current_iteration++;
+prd.updated_at = now;
+
+// Update top-level status
+const allCompleted = prd.tasks.every(t =>
+  t.status === 'completed' || t.status === 'skipped'
+);
+const anyFailed = prd.tasks.some(t => t.status === 'failed');
+const anyBlocked = prd.tasks.some(t => t.status === 'blocked');
+
+if (allCompleted) {
+  prd.status = 'completed';
+} else if (anyFailed || anyBlocked) {
+  prd.status = 'partial';
+} else {
+  prd.status = 'in_progress';
+}
+
 writeJSON('.ralph/prd.json', prd);
 ```
 
-### 4. Update progress.txt
+### 6. Update progress.txt
 
 **Append learnings to progress.txt:**
 
@@ -85,10 +149,17 @@ writeJSON('.ralph/prd.json', prd);
 
 ### Task Completed
 [{current_task_id}] {current_task_description}
+Category: {current_task_category}
+Status: {task.status}
+Commit: {COMMIT_HASH}
 
 ### Files Changed
-- Created: {files_created}
-- Modified: {files_modified}
+- Created: {task.files_changed.created}
+- Modified: {task.files_changed.modified}
+
+### Acceptance Criteria
+{current_task_criteria}
+Result: ✅ Met / ❌ Not met
 
 ### Learnings
 {What was learned during this task}
@@ -99,20 +170,38 @@ writeJSON('.ralph/prd.json', prd);
 {What the next iteration should know}
 ```
 
-### 5. Verify Commit
+### 7. Commit prd.json and progress.txt Updates
+
+**Stage and commit the tracking files separately:**
+
+```bash
+git add .ralph/prd.json .ralph/progress.txt
+git commit -m "$(cat <<'EOF'
+chore(ralph): update progress - task {current_task_id}/{tasks_total}
+
+Iteration {current_iteration} complete
+Status: {task.status}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+### 8. Verify Commit
 
 **Check commit was created:**
 
 ```bash
-git log -1 --oneline
+git log -2 --oneline
 ```
 
 **Expected output:**
 ```
-abc1234 feat(ralph): {current_task_description}
+def5678 chore(ralph): update progress - task {id}/{total}
+abc1234 feat(scope): {current_task_description}
 ```
 
-### 6. Log Activity (if verbose)
+### 9. Log Activity (if verbose)
 
 **If {verbose_mode} = true:**
 
@@ -120,9 +209,13 @@ Append to `.ralph/logs/{date}.log`:
 ```
 [{timestamp}] TASK COMPLETED
   Task: [{current_task_id}] {current_task_description}
-  Commit: {commit_hash}
-  Files: {file_count} changed
+  Category: {current_task_category}
+  Status: {task.status}
+  Commit: {COMMIT_HASH}
+  Files: {file_count} changed ({created_count} created, {modified_count} modified)
+  Duration: {duration_seconds}s
   Iteration: {current_iteration}
+  Validation: {validation_result}
 ```
 
 ---
@@ -134,13 +227,17 @@ Changes Committed:
 
 | Field | Value |
 |-------|-------|
-| Commit | {commit_hash} |
-| Task | [{current_task_id}] ✅ |
+| Commit | {COMMIT_HASH} |
+| Task | [{current_task_id}] {current_task_description} |
+| Category | {current_task_category} |
+| Status | {task.status} |
 | Iteration | {current_iteration} |
 | Files | {file_count} changed |
+| Duration | {duration_seconds}s |
+| Validation | {validation_result} |
 
-prd.json: Updated task {current_task_id} to passes: true
-progress.txt: Added iteration {current_iteration} learnings
+prd.json: Task {current_task_id} → {task.status}, history entry added
+progress.txt: Iteration {current_iteration} learnings appended
 
 -> Checking completion...
 ```
@@ -163,6 +260,13 @@ progress.txt: Added iteration {current_iteration} learnings
 2. Retry write
 3. If still fails, output error and stop
 
+**If task was failed in step-02:**
+
+1. Still commit whatever was done (partial progress)
+2. task.status remains "failed"
+3. history entry records action: "failed"
+4. step-04 will handle downstream blocking
+
 ---
 
 ## NEXT STEP: