@atlashub/smartstack-cli 1.35.0 → 1.37.0

package/templates/skills/ralph-loop/steps/step-00-init.md

@@ -1,6 +1,6 @@
 ---
 name: step-00-init
-description: Initialize Ralph loop - parse args, verify MCP, setup state
+description: Initialize Ralph loop - parse args, verify MCP, setup state, migrate v1
 next_step: steps/step-01-task.md
 ---
 
@@ -13,10 +13,11 @@ next_step: steps/step-01-task.md
 - ONLY check for resume if -r flag is set
 - YOU ARE AN INITIALIZER, not an executor
 - FORBIDDEN to load step-01 until init is complete
+- ALWAYS check prd.json version and migrate if v1
 
 ## YOUR TASK:
 
-Initialize the Ralph loop by parsing flags, verifying MCP availability, and setting up the execution environment.
+Initialize the Ralph loop by parsing flags, verifying MCP availability, setting up the execution environment, and validating integrity on resume.
 
 ---
 
@@ -73,26 +74,32 @@ mcp__smartstack__validate_conventions:
 
 **Check Context7 MCP:**
 ```
-mcp__plugin_context7_context7__resolve-library-id:
+mcp__context7__resolve-library-id:
   libraryName: "test"
   query: "connectivity check"
   (just to verify connectivity)
 ```
 
+**Record MCP status for metadata:**
+```
+{mcp_smartstack} = true/false
+{mcp_context7}   = true/false
+```
+
 **If ANY MCP fails:**
 ```
 ╔══════════════════════════════════════════════════════════════════╗
-║  ❌ MCP SERVER UNAVAILABLE                                        ║
+║  ❌ MCP SERVER UNAVAILABLE                                      ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Server: {failed_server}                                          ║
-║  Status: Connection failed                                        ║
+║  Server: {failed_server}                                        ║
+║  Status: Connection failed                                      ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  RALPH CANNOT PROCEED WITHOUT MCP                                 ║
-║                                                                    ║
-║  Troubleshooting:                                                  ║
-║  1. Run: smartstack check-mcp                                      ║
-║  2. Restart Claude Code                                            ║
-║  3. Check MCP server configuration                                 ║
+║  RALPH CANNOT PROCEED WITHOUT MCP                               ║
+║                                                                  ║
+║  Troubleshooting:                                                ║
+║  1. Run: smartstack check-mcp                                    ║
+║  2. Restart Claude Code                                          ║
+║  3. Check MCP server configuration                               ║
 ╚══════════════════════════════════════════════════════════════════╝
 
 STOP - Do not proceed.
@@ -103,16 +110,122 @@ STOP - Do not proceed.
 **If {resume_mode} = true:**
 
 1. Check for existing `.ralph/prd.json`
-2. If found:
-   - Read prd.json to restore state
-   - Read progress.txt for context
-   - Set {current_iteration} from state
-   - Continue to step-01
-3. If not found:
+2. If not found:
    - Error: "No active Ralph loop to resume"
    - Ask user to start new loop
+   - STOP
+
+3. If found, **validate schema version:**
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
 
-### 4. Initialize .ralph/ Structure
+// v1 detection: has "passes" field in tasks or no "$version"
+const isV1 = !prd.$version || prd.tasks?.some(t => 'passes' in t);
+
+if (isV1) {
+  // AUTO-MIGRATE v1 → v2
+  migrateV1toV2(prd);
+}
+```
+
+**v1 → v2 Migration logic:**
+
+```javascript
+function migrateV1toV2(prd) {
+  prd.$version = "2.0.0";
+  prd.status = prd.tasks.every(t => t.passes) ? "completed" : "in_progress";
+  prd.updated_at = new Date().toISOString();
+
+  // Migrate source field
+  if (typeof prd.source === 'string') {
+    prd.source = { type: "ba-handoff", handoff_path: prd.source, frd_path: null, brd_path: null };
+  } else if (prd.source === null || prd.source === undefined) {
+    prd.source = null;
+  }
+
+  // Group flat config fields
+  prd.config = {
+    max_iterations: prd.max_iterations || 50,
+    completion_promise: prd.completion_promise || "COMPLETE",
+    current_iteration: prd.current_iteration || 1
+  };
+  delete prd.max_iterations;
+  delete prd.completion_promise;
+  delete prd.current_iteration;
+
+  // Add metadata
+  prd.metadata = {
+    cli_version: "unknown (migrated)",
+    branch: getCurrentBranch(),
+    project_path: process.cwd(),
+    mcp_servers: { smartstack: {mcp_smartstack}, context7: {mcp_context7} }
+  };
+
+  // Migrate tasks
+  prd.tasks = prd.tasks.map(t => ({
+    id: t.id,
+    description: t.description,
+    status: t.passes ? "completed" : "pending",
+    category: "other",
+    dependencies: [],
+    acceptance_criteria: null,
+    started_at: null,
+    completed_at: t.passes ? prd.updated_at : null,
+    iteration: null,
+    commit_hash: null,
+    files_changed: { created: [], modified: [] },
+    validation: null,
+    error: null
+  }));
+
+  // Initialize history
+  prd.history = [];
+
+  // Write migrated file
+  writeJSON('.ralph/prd.json', prd);
+  echo "✅ Migrated prd.json from v1 to v2";
+}
+```
+
+4. **Validate integrity (v2 resume):**
+
+```bash
+# Check branch consistency
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+PRD_BRANCH={prd.metadata.branch}
+
+if [ "$CURRENT_BRANCH" != "$PRD_BRANCH" ]; then
+  echo "⚠️ Branch mismatch: prd.json was created on '$PRD_BRANCH', now on '$CURRENT_BRANCH'"
+  # Ask user: continue on current branch or switch
+  AskUserQuestion:
+    header: "Branch"
+    question: "prd.json was created on '$PRD_BRANCH' but you're on '$CURRENT_BRANCH'. Continue?"
+    options:
+      - label: "Continue on $CURRENT_BRANCH"
+        description: "Update metadata and continue"
+      - label: "Cancel"
+        description: "Switch branch manually first"
+fi
+
+# Check for external commits since last update
+LAST_UPDATED={prd.updated_at}
+EXTERNAL_COMMITS=$(git log --since="$LAST_UPDATED" --oneline --not --author="Co-Authored-By: Claude" | wc -l)
+
+if [ "$EXTERNAL_COMMITS" -gt 0 ]; then
+  echo "⚠️ $EXTERNAL_COMMITS external commits detected since last Ralph iteration"
+  echo "   prd.json state may not reflect current code state"
+fi
+```
+
+5. **Restore state from prd.json:**
+   - Read `prd.config.current_iteration` → `{current_iteration}`
+   - Read `prd.config.completion_promise` → `{completion_promise}`
+   - Read `prd.config.max_iterations` → `{max_iterations}`
+   - Read progress.txt for context
+   - Continue to step-01
+
+### 4. Initialize .ralph/ Structure (new loop)
 
 **Create directory structure:**
 
@@ -149,7 +262,27 @@ AskUserQuestion:
       description: "Specify custom text"
 ```
 
-### 6. Log Initialization
+### 6. Collect Metadata
+
+**Gather execution context:**
+
+```bash
+CLI_VERSION=$(node -e "console.log(require('package.json').version)" 2>/dev/null || echo "unknown")
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+PROJECT_PATH=$(pwd)
+```
+
+**Store metadata for prd.json creation (step-01):**
+```
+{metadata} = {
+  cli_version: CLI_VERSION,
+  branch: CURRENT_BRANCH,
+  project_path: PROJECT_PATH,
+  mcp_servers: { smartstack: {mcp_smartstack}, context7: {mcp_context7} }
+}
+```
+
+### 7. Log Initialization
 
 **If {verbose_mode} = true:**
 
@@ -159,25 +292,29 @@ Write to `.ralph/logs/{timestamp}.log`:
 Task: {task_description}
 Max iterations: {max_iterations}
 Completion promise: {completion_promise}
-MCP Status: SmartStack ✅, Context7 ✅
+MCP Status: SmartStack {mcp_smartstack ? "✅" : "❌"}, Context7 {mcp_context7 ? "✅" : "❌"}
+Schema: v2.0.0
+Branch: {CURRENT_BRANCH}
 ```
 
-### 7. Show Summary and Proceed
+### 8. Show Summary and Proceed
 
 **Always show COMPACT summary:**
 
 ```
 ╔══════════════════════════════════════════════════════════════════╗
-║  RALPH LOOP INITIALIZED                                           ║
+║  RALPH LOOP INITIALIZED                                         ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Task: {task_description}                                         ║
-║  Max iterations: {max_iterations}                                 ║
-║  Completion: <promise>{completion_promise}</promise>              ║
-║  MCP: ✅ Ready                                                    ║
+║  Task: {task_description}                                       ║
+║  Max iterations: {max_iterations}                               ║
+║  Completion: <promise>{completion_promise}</promise>             ║
+║  MCP: ✅ Ready                                                  ║
+║  Schema: v2.0.0                                                 ║
+║  Branch: {CURRENT_BRANCH}                                       ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Files:                                                           ║
-║  - .ralph/prd.json (tasks)                                        ║
-║  - .ralph/progress.txt (memory)                                   ║
+║  Files:                                                          ║
+║  - .ralph/prd.json (tasks)                                       ║
+║  - .ralph/progress.txt (memory)                                  ║
 ╚══════════════════════════════════════════════════════════════════╝
 
 -> Loading tasks...
@@ -193,6 +330,9 @@ MCP Status: SmartStack ✅, Context7 ✅
 - MCP servers verified and available
 - .ralph/ directory structure created
 - Completion promise defined
+- Metadata collected (branch, version, MCP status)
+- v1 prd.json migrated to v2 (if resume)
+- Branch integrity validated (if resume)
 - Output is COMPACT
 - Proceeded to step-01 immediately after summary
 

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...
 ```