@atlashub/smartstack-cli 1.35.0 → 1.36.0

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

@@ -1,6 +1,6 @@
 ---
 name: step-01-task
-description: Load or create tasks from prd.json
+description: Load or create tasks from prd.json (v2 schema)
 next_step: steps/step-02-execute.md
 ---
 
@@ -8,7 +8,7 @@ next_step: steps/step-02-execute.md
 
 ## YOUR TASK:
 
-Load the current task from prd.json or create initial task breakdown.
+Load the current task from prd.json or create initial task breakdown with categories, dependencies, and acceptance criteria.
 
 **ULTRA THINK about task decomposition.**
 
@@ -20,9 +20,9 @@ Load the current task from prd.json or create initial task breakdown.
 
 **If `.ralph/prd.json` exists:**
 - Read and parse the file
-- Find the next task with `passes: false`
-- Load into state
-- Skip to step 4
+- Verify `$version` is `"2.0.0"` (if not, STOP - run step-00 migration first)
+- Find the next eligible task (see step 5)
+- Skip to step 5
 
 **If `.ralph/prd.json` does NOT exist:**
 - Continue to step 2 (create tasks)
@@ -35,42 +35,162 @@ Load the current task from prd.json or create initial task breakdown.
 - What order should they be executed?
 - What are the success criteria for each?
 - What files will be modified?
+- What layer does each task belong to?
+- What dependencies exist between tasks?
+
+**Check for BA handoff source:**
+
+```bash
+# If a handoff document exists, use it to derive tasks
+HANDOFF=$(find . -path "*development-handoff*" -name "*.md" | head -1)
+BA_OUTPUT=$(find . -path ".claude/output/ba/*" -name "4-*.md" | head -1)
+SOURCE_PATH=${HANDOFF:-$BA_OUTPUT}
+```
+
+**If handoff found:**
+- Read the handoff document
+- Derive tasks from its specifications (per-layer breakdown)
+- Set `source.type = "ba-handoff"` and `source.handoff_path`
+- Look for FRD and BRD in the same directory
+
+**If no handoff:**
+- Generate task breakdown from `{task_description}`
+- Set `source = null`
 
 **Generate task breakdown:**
 
-For `{task_description}`, identify 3-10 subtasks.
+For `{task_description}`, identify **3-30 subtasks** organized by category.
+
+**Task categories (use SmartStack layer order):**
+
+| Category | Description | Examples |
+|----------|-------------|---------|
+| `domain` | Domain entities and value objects | Create entities, enums, interfaces |
+| `application` | CQRS handlers, DTOs, validators | Commands, Queries, DTOs, FluentValidation |
+| `infrastructure` | EF Core, external services | DbContext configs, migrations, services |
+| `api` | Controllers, middleware | REST endpoints, filters, middleware |
+| `frontend` | React pages, components, hooks | Pages, API services, React Query hooks |
+| `i18n` | Translations | Translation JSON files |
+| `test` | Unit and integration tests | xUnit tests, React testing library |
+| `validation` | Build, lint, MCP checks | dotnet build, pnpm build, MCP validate |
+| `other` | Anything else | Documentation, configuration |
 
 **Example for "implement user authentication":**
 ```json
 {
   "tasks": [
-    { "id": 1, "description": "Create User entity in Domain layer", "passes": false },
-    { "id": 2, "description": "Add User DbSet to ApplicationDbContext", "passes": false },
-    { "id": 3, "description": "Create EF Core migration", "passes": false },
-    { "id": 4, "description": "Implement IPasswordService", "passes": false },
-    { "id": 5, "description": "Implement IJwtService", "passes": false },
-    { "id": 6, "description": "Create AuthController with login endpoint", "passes": false },
-    { "id": 7, "description": "Add authentication middleware", "passes": false },
-    { "id": 8, "description": "Write integration tests", "passes": false }
+    {
+      "id": 1,
+      "description": "Create User entity in SmartStack.Domain/Entities/Business/",
+      "status": "pending",
+      "category": "domain",
+      "dependencies": [],
+      "acceptance_criteria": "Entity compiles with all required properties per handoff spec"
+    },
+    {
+      "id": 2,
+      "description": "Add User DbSet to ApplicationDbContext and create EF Core configuration",
+      "status": "pending",
+      "category": "infrastructure",
+      "dependencies": [1],
+      "acceptance_criteria": "DbContext compiles, configuration maps all properties"
+    },
+    {
+      "id": 3,
+      "description": "Create EF Core migration for User table",
+      "status": "pending",
+      "category": "infrastructure",
+      "dependencies": [2],
+      "acceptance_criteria": "Migration applies without errors, 3 files present"
+    },
+    {
+      "id": 4,
+      "description": "Implement IPasswordService and IJwtService",
+      "status": "pending",
+      "category": "application",
+      "dependencies": [1],
+      "acceptance_criteria": "Services compile, follow existing patterns"
+    },
+    {
+      "id": 5,
+      "description": "Create CQRS Commands: LoginCommand + RegisterCommand with handlers",
+      "status": "pending",
+      "category": "application",
+      "dependencies": [4],
+      "acceptance_criteria": "Handlers compile, validators defined"
+    },
+    {
+      "id": 6,
+      "description": "Create AuthController with login/register endpoints",
+      "status": "pending",
+      "category": "api",
+      "dependencies": [5],
+      "acceptance_criteria": "Endpoints respond correctly, Swagger displays them"
+    },
+    {
+      "id": 7,
+      "description": "Write unit tests for User entity and validators",
+      "status": "pending",
+      "category": "test",
+      "dependencies": [5],
+      "acceptance_criteria": "All tests pass, >80% coverage on new code"
+    },
+    {
+      "id": 8,
+      "description": "Run dotnet build, dotnet test, MCP validate_conventions",
+      "status": "pending",
+      "category": "validation",
+      "dependencies": [6, 7],
+      "acceptance_criteria": "Build succeeds, all tests pass, MCP validation clean"
+    }
   ]
 }
 ```
 
-### 3. Create prd.json
+**Task count validation:**
+- MINIMUM: 3 tasks (anything less is too coarse)
+- MAXIMUM: 30 tasks (anything more needs re-grouping)
+- If over 30, merge related subtasks into larger units
+
+### 3. Create prd.json (v2)
 
 **Write `.ralph/prd.json`:**
 
 ```json
 {
+  "$version": "2.0.0",
   "feature": "{task_description}",
-  "created": "{timestamp}",
-  "max_iterations": {max_iterations},
-  "completion_promise": "{completion_promise}",
-  "current_iteration": 1,
-  "tasks": [
-    { "id": 1, "description": "...", "passes": false },
-    { "id": 2, "description": "...", "passes": false }
-  ]
+  "status": "in_progress",
+  "created": "{ISO_TIMESTAMP}",
+  "updated_at": "{ISO_TIMESTAMP}",
+  "metadata": {metadata},
+  "config": {
+    "max_iterations": {max_iterations},
+    "completion_promise": "{completion_promise}",
+    "current_iteration": 1
+  },
+  "source": {source_object_or_null},
+  "tasks": [{generated_tasks_with_all_fields}],
+  "history": []
+}
+```
+
+**IMPORTANT: Every task MUST have ALL fields:**
+```json
+{
+  "id": 1,
+  "description": "...",
+  "status": "pending",
+  "category": "domain|application|infrastructure|api|frontend|i18n|test|validation|other",
+  "dependencies": [],
+  "acceptance_criteria": "...",
+  "started_at": null,
+  "completed_at": null,
+  "iteration": null,
+  "commit_hash": null,
+  "files_changed": { "created": [], "modified": [] },
+  "validation": null,
+  "error": null
 }
 ```
 
@@ -81,6 +201,8 @@ For `{task_description}`, identify 3-10 subtasks.
 
 ## Task: {task_description}
 ## Started: {timestamp}
+## Schema: v2.0.0
+## Source: {source_type or "direct"}
 
 ---
 
@@ -93,27 +215,102 @@ Starting fresh implementation.
 (To be updated after each iteration)
 ```
 
-### 4. Find Current Task
+### 4. Validate Task Integrity
 
-**Find the next task with `passes: false`:**
+**After creation, verify:**
 
 ```javascript
-const currentTask = tasks.find(t => !t.passes);
+// Check all tasks have required fields
+const requiredFields = ['id', 'description', 'status', 'category',
+  'dependencies', 'acceptance_criteria', 'started_at', 'completed_at',
+  'iteration', 'commit_hash', 'files_changed', 'validation', 'error'];
+
+for (const task of prd.tasks) {
+  for (const field of requiredFields) {
+    if (!(field in task)) {
+      ERROR: "Task ${task.id} missing field: ${field}";
+    }
+  }
+}
+
+// Check dependency references are valid
+const taskIds = prd.tasks.map(t => t.id);
+for (const task of prd.tasks) {
+  for (const dep of task.dependencies) {
+    if (!taskIds.includes(dep)) {
+      ERROR: "Task ${task.id} depends on non-existent task ${dep}";
+    }
+  }
+}
+
+// Check no circular dependencies
+// (simple: a task cannot depend on a task with higher or equal id)
+for (const task of prd.tasks) {
+  for (const dep of task.dependencies) {
+    if (dep >= task.id) {
+      ERROR: "Task ${task.id} has forward/circular dependency on task ${dep}";
+    }
+  }
+}
+
+// Check task count
+if (prd.tasks.length < 3 || prd.tasks.length > 30) {
+  WARNING: "Task count ${prd.tasks.length} outside recommended range (3-30)";
+}
+```
+
+### 5. Find Current Task
+
+**Find the next eligible task:**
+
+```javascript
+function findNextTask(tasks) {
+  for (const task of tasks) {
+    if (task.status !== 'pending') continue;
+
+    // Check all dependencies are completed
+    const depsOk = task.dependencies.every(depId => {
+      const dep = tasks.find(t => t.id === depId);
+      return dep && dep.status === 'completed';
+    });
+
+    // Check if any dependency failed (→ block this task)
+    const depsBlocked = task.dependencies.some(depId => {
+      const dep = 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`;
+      continue;
+    }
+
+    if (depsOk) return task;
+  }
+  return null; // No eligible tasks
+}
+
+const currentTask = findNextTask(prd.tasks);
 ```
 
-**If all tasks are `passes: true`:**
-- This shouldn't happen in step-01
-- If it does, skip to step-05 (report)
+**If no eligible task found:**
+- Check if all tasks are completed → skip to step-05 (report)
+- Check if remaining tasks are all blocked → report as partial, step-05
+- Otherwise → unexpected state, STOP
 
 **Store in state:**
 ```
 {current_task_id}          = currentTask.id
 {current_task_description} = currentTask.description
-{tasks_completed}          = tasks.filter(t => t.passes).length
+{current_task_category}    = currentTask.category
+{current_task_criteria}    = currentTask.acceptance_criteria
+{tasks_completed}          = tasks.filter(t => t.status === 'completed').length
 {tasks_total}              = tasks.length
+{tasks_blocked}            = tasks.filter(t => t.status === 'blocked').length
 ```
 
-### 5. Read Previous Progress
+### 6. Read Previous Progress
 
 **If iteration > 1:**
 
@@ -123,23 +320,26 @@ Read `.ralph/progress.txt` to understand:
 - Files that were modified
 - Issues encountered
 
-**This provides context for the current iteration.**
+**Also read `history[]` from prd.json for structured context.**
 
-### 6. Show Task Status
+### 7. Show Task Status
 
 **Display current state:**
 
 ```
 ╔══════════════════════════════════════════════════════════════════╗
-║  ITERATION {current_iteration} / {max_iterations}                 ║
+║  ITERATION {current_iteration} / {max_iterations}               ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Progress: {tasks_completed} / {tasks_total} tasks complete       ║
-║                                                                    ║
-║  Current Task:                                                     ║
-║  [{current_task_id}] {current_task_description}                   ║
+║  Progress: {tasks_completed} / {tasks_total} tasks complete     ║
+║  Blocked:  {tasks_blocked}                                      ║
+║                                                                  ║
+║  Current Task:                                                   ║
+║  [{current_task_id}] {current_task_description}                 ║
+║  Category: {current_task_category}                               ║
+║  Criteria: {current_task_criteria}                               ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Previous Learnings:                                               ║
-║  {summary from progress.txt}                                       ║
+║  Previous Learnings:                                             ║
+║  {summary from progress.txt}                                    ║
 ╚══════════════════════════════════════════════════════════════════╝
 
 -> Executing task...
@@ -157,7 +357,10 @@ Task Loaded:
 | Iteration | {current_iteration} / {max_iterations} |
 | Task ID | {current_task_id} |
 | Task | {current_task_description} |
+| Category | {current_task_category} |
+| Criteria | {current_task_criteria} |
 | Progress | {tasks_completed} / {tasks_total} |
+| Blocked | {tasks_blocked} |
 
 -> Executing...
 ```

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: