@atlashub/smartstack-cli 1.35.0 → 1.36.0

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

@@ -111,7 +111,7 @@ The loop only stops when this exact tag is output or max iterations reached.
 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 tasks)
+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
@@ -131,6 +131,10 @@ The loop only stops when this exact tag is output or max iterations reached.
 | `{current_iteration}` | number | Current iteration count |
 | `{tasks_completed}` | number | Number of tasks completed |
 | `{tasks_total}` | number | Total tasks in prd.json |
+| `{task_status}` | string | Current task status (pending/in_progress/completed/failed/skipped/blocked) |
+| `{task_category}` | string | Task category (domain/application/infrastructure/api/frontend/i18n/test/validation) |
+| `{files_created}` | string[] | Files created during current task |
+| `{files_modified}` | string[] | Files modified during current task |
 
 </state_variables>
 
@@ -190,19 +194,58 @@ Before ANY work, verify MCP servers:
 **prd.json structure:**
 ```json
 {
+  "$version": "2.0.0",
   "feature": "{task_description}",
-  "created": "2024-01-01T00:00:00Z",
-  "max_iterations": 50,
-  "completion_promise": "COMPLETE",
-  "source": null,
+  "status": "in_progress",
+  "created": "2026-01-30T15:00:00.000Z",
+  "updated_at": "2026-01-30T16:30:00.000Z",
+  "metadata": {
+    "cli_version": "1.36.0",
+    "branch": "feature/user-auth",
+    "project_path": "/path/to/project",
+    "mcp_servers": { "smartstack": true, "context7": true }
+  },
+  "config": {
+    "max_iterations": 50,
+    "completion_promise": "COMPLETE",
+    "current_iteration": 1
+  },
+  "source": {
+    "type": "ba-handoff",
+    "handoff_path": "path/to/4-development-handoff.md",
+    "frd_path": null,
+    "brd_path": null
+  },
   "tasks": [
-    { "id": 1, "description": "Task 1", "passes": false },
-    { "id": 2, "description": "Task 2", "passes": false }
-  ]
+    {
+      "id": 1,
+      "description": "Create User entity in Domain layer",
+      "status": "pending",
+      "category": "domain",
+      "dependencies": [],
+      "acceptance_criteria": "Entity compiles, properties match handoff spec",
+      "started_at": null,
+      "completed_at": null,
+      "iteration": null,
+      "commit_hash": null,
+      "files_changed": { "created": [], "modified": [] },
+      "validation": null,
+      "error": null
+    }
+  ],
+  "history": []
 }
 ```
 
-> **`source` field:** Optional path to the BA handoff document that generated this task list (set by `/business-analyse` step-05). When present, Ralph Loop can reference the handoff for detailed specifications. `null` when tasks are created directly by Ralph Loop.
+> **Schema v2 notes:**
+> - `$version`: Schema version for forward migration
+> - `status` (top-level): `pending` | `in_progress` | `completed` | `failed` | `partial`
+> - `source.type`: `ba-handoff` | `direct` | `feature-full` — `null` when tasks are created directly by Ralph Loop
+> - `task.status`: `pending` | `in_progress` | `completed` | `failed` | `skipped` | `blocked`
+> - `task.category`: `domain` | `application` | `infrastructure` | `api` | `frontend` | `i18n` | `test` | `validation` | `other`
+> - `task.dependencies`: Array of task IDs that must be `completed` before this task can start
+> - `history`: Structured iteration journal (replaces unstructured progress.txt for traceability)
+> - **Backward compatibility**: step-00 auto-migrates v1 prd.json (with `passes` boolean) to v2 format
 </file_structure>
 
 <execution_rules>
@@ -217,11 +260,14 @@ Before ANY work, verify MCP servers:
 
 <success_criteria>
 
-- All tasks in prd.json have `passes: true`
+- All tasks in prd.json have `status: "completed"` (or `"skipped"`)
+- No tasks with `status: "blocked"` remain
 - MCP validations pass
-- Git commits atomic per task
+- Git commits atomic per task with `commit_hash` tracked
+- `history[]` contains entry for every completed task
 - Completion promise output when genuinely complete
 - Final report generated in `.ralph/reports/`
+- `prd.json` top-level `status` set to `"completed"` or `"partial"`
 </success_criteria>
 
 <available_commands>

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