@atlashub/smartstack-cli 1.34.0 → 1.36.0

package/templates/skills/gitflow/steps/step-pr.md

@@ -16,23 +16,21 @@ Create a pull request with proper target, title, and description based on branch
 
 ## EXECUTION SEQUENCE:
 
-### 1. Detect Git Provider
+### 1. Load Config and Detect Provider
 
 ```bash
-REMOTE_URL=$(git remote get-url origin)
-
-if [[ "$REMOTE_URL" == *"github.com"* ]]; then
-  GIT_PROVIDER="github"
-elif [[ "$REMOTE_URL" == *"dev.azure.com"* ]] || [[ "$REMOTE_URL" == *"visualstudio.com"* ]]; then
-  GIT_PROVIDER="azuredevops"
-  # Extract Azure DevOps details
-  [[ "$REMOTE_URL" =~ dev\.azure\.com/([^/]+)/([^/]+)/_git/([^/]+) ]] && {
+# Load GitFlow config (sets GF_* variables)
+read_gitflow_config || { echo "❌ Run /gitflow init first."; exit 1; }
+
+GIT_PROVIDER="$GF_PROVIDER"
+
+# Extract Azure DevOps details if needed
+if [ "$GIT_PROVIDER" = "azuredevops" ]; then
+  [[ "$GF_REMOTE_URL" =~ dev\.azure\.com/([^/]+)/([^/]+)/_git/([^/]+) ]] && {
     AZURE_ORG="${BASH_REMATCH[1]}"
     AZURE_PROJECT="${BASH_REMATCH[2]}"
     AZURE_REPO="${BASH_REMATCH[3]}"
   }
-else
-  GIT_PROVIDER="unknown"
 fi
 ```
 
@@ -42,10 +40,10 @@ fi
 CURRENT=$(git rev-parse --abbrev-ref HEAD)
 
 case "$CURRENT" in
-  feature/*) TARGET_BRANCH="develop" ;;
-  release/*) TARGET_BRANCH="main" ;;
-  hotfix/*)  TARGET_BRANCH="main" ;;
-  *)         TARGET_BRANCH="develop" ;;
+  ${GF_FEATURE_PREFIX}*) TARGET_BRANCH="$GF_DEVELOP_BRANCH" ;;
+  ${GF_RELEASE_PREFIX}*) TARGET_BRANCH="$GF_MAIN_BRANCH" ;;
+  ${GF_HOTFIX_PREFIX}*)  TARGET_BRANCH="$GF_MAIN_BRANCH" ;;
+  *)                     TARGET_BRANCH="$GF_DEVELOP_BRANCH" ;;
 esac
 ```
 
@@ -90,16 +88,26 @@ EXISTING_PR=$(gh pr list --head "$CURRENT" --json number --jq '.[0].number' 2>/d
 ### 4. Run Pre-PR Checks
 
 ```bash
-# Build check
+# Build check (multi-runtime detection)
 echo "Running build check..."
-dotnet build --no-restore 2>&1 || {
-  echo "❌ Build failed. Fix before creating PR."
-  STOP
-}
-
-# Migration check
-echo "Checking migrations..."
-dotnet ef migrations list 2>&1 || echo "No migrations or EF Core not configured"
+if [ -f "*.sln" ] || ls *.csproj 2>/dev/null | head -1 > /dev/null; then
+  dotnet build --no-restore 2>&1 || {
+    echo "❌ .NET build failed. Fix before creating PR."
+    STOP
+  }
+  # Migration check
+  echo "Checking migrations..."
+  dotnet ef migrations list 2>&1 || echo "No migrations or EF Core not configured"
+elif [ -f "package.json" ]; then
+  npm run build 2>&1 || {
+    echo "❌ npm build failed. Fix before creating PR."
+    STOP
+  }
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+  echo "Python project detected — skipping build check"
+else
+  echo "⚠️ No known build system detected — skipping build check"
+fi
 ```
 
 ### 5. Generate PR Content
@@ -112,7 +120,7 @@ BRANCH_TYPE=$(echo $CURRENT | cut -d'/' -f1)
 case "$BRANCH_TYPE" in
   feature) TITLE="feat: $BRANCH_NAME" ;;
   hotfix)  TITLE="fix: $BRANCH_NAME" ;;
-  release) TITLE="release: v$(grep -oP '"current":\s*"\K[^"]+' .claude/gitflow/config.json)" ;;
+  release) TITLE="release: v$GF_VERSION" ;;
 esac
 ```
 
@@ -187,13 +195,19 @@ fi
 ### 8. Store PR Info
 
 ```bash
-# Save for merge step
+# Persist PR info for merge step (uses config path for portability)
+CONFIG_DIR=$(dirname "$GF_CONFIG_FILE")
+cat > "$CONFIG_DIR/cache/pr-state.json" << EOF
 {
-  "pr_number": $PR_NUMBER,
+  "pr_number": "$PR_NUMBER",
   "pr_url": "$PR_URL",
+  "source_branch": "$CURRENT",
   "target_branch": "$TARGET_BRANCH",
-  "git_provider": "$GIT_PROVIDER"
+  "git_provider": "$GIT_PROVIDER",
+  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 }
+EOF
+echo "✓ PR state saved to $CONFIG_DIR/cache/pr-state.json"
 ```
 
 ### 9. Summary

package/templates/skills/gitflow/steps/step-start.md

@@ -31,18 +31,22 @@ Create a new feature/release/hotfix branch with optional worktree setup.
 
 ## EXECUTION SEQUENCE:
 
-### 1. Analyze Context
+### 1. Load Config and Analyze Context
 
 ```bash
+# Load GitFlow config (sets GF_* variables)
+# See _shared.md → READ_GITFLOW_CONFIG for all variables
+read_gitflow_config || { echo "❌ Run /gitflow init first."; exit 1; }
+
 CURRENT_BRANCH=$(git branch --show-current)
 git fetch origin --quiet
 
-# Version detection
-VERSION=$(grep -oP '"current":\s*"\K[^"]+' .claude/gitflow/config.json 2>/dev/null || echo "0.1.0")
+# Version from config
+VERSION="$GF_VERSION"
 LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")
 
 # Develop ahead of main?
-DEVELOP_AHEAD=$(git rev-list --count origin/main..origin/develop 2>/dev/null || echo "0")
+DEVELOP_AHEAD=$(git rev-list --count origin/$GF_MAIN_BRANCH..origin/$GF_DEVELOP_BRANCH 2>/dev/null || echo "0")
 
 # Working directory status
 DIRTY=$(git status --porcelain | wc -l)
@@ -129,17 +133,17 @@ esac
 
 ### 6. Create Branch and Worktree
 
-**Read worktree mode from config:**
+**Read worktree mode from config (already loaded by read_gitflow_config):**
 ```bash
-WORKTREE_MODE=$(grep -oP '"mode":\s*"\K[^"]+' .claude/gitflow/config.json 2>/dev/null || echo "organized")
+WORKTREE_MODE="$GF_WORKTREE_MODE"
 ```
 
-**Mode: organized**
+**Mode: organized (uses absolute paths from config)**
 ```bash
 case "$branch_type" in
-  feature) WORKTREE_PATH="../features/$BRANCH_NAME" ;;
-  release) WORKTREE_PATH="../releases/v$VERSION" ;;
-  hotfix)  WORKTREE_PATH="../hotfixes/$BRANCH_NAME" ;;
+  feature) WORKTREE_PATH="$GF_FEATURES_PATH/$BRANCH_NAME" ;;
+  release) WORKTREE_PATH="$GF_RELEASES_PATH/v$VERSION" ;;
+  hotfix)  WORKTREE_PATH="$GF_HOTFIXES_PATH/$BRANCH_NAME" ;;
 esac
 
 mkdir -p "$(dirname $WORKTREE_PATH)"
@@ -181,13 +185,15 @@ API_DIR=$(find "$WORKTREE_PATH" -type d -name "*.Api" -path "*/src/*" | head -1)
 WEB_DIR=$(find "$WORKTREE_PATH" -type d -name "*-web" -path "*/web/*" | head -1)
 
 # Generate unique ports based on branch name hash (to avoid conflicts between worktrees)
-HASH=$(echo "$BRANCH_NAME" | md5sum | cut -c1-4)
+# Use shasum (portable across macOS/Linux/Windows Git Bash) with md5sum fallback
+HASH=$(echo "$BRANCH_NAME" | shasum 2>/dev/null || echo "$BRANCH_NAME" | md5sum 2>/dev/null || echo "$BRANCH_NAME" | cksum)
+HASH=$(echo "$HASH" | cut -c1-4)
 HASH_NUM=$((16#$HASH % 100))
 API_PORT=$((5200 + HASH_NUM))
 WEB_PORT=$((5300 + HASH_NUM))
 
-# Project and DB naming
-PROJECT_NAME=$(basename $(pwd) | tr '[:upper:]' '[:lower:]')
+# Project name from config (not from pwd)
+PROJECT_NAME=$(echo "$GF_PROJECT_NAME" | tr '[:upper:]' '[:lower:]')
 DB_NAME=$(echo "${PROJECT_NAME}_${branch_type}_${BRANCH_NAME}" | cut -c1-63)
 ```
 

package/templates/skills/gitflow/templates/config.json

@@ -2,11 +2,19 @@
   "version": "2.0.0",
   "repository": {
     "name": "",
+    "rootFolder": "",
+    "nameVariants": {
+      "pascalCaseDot": "",
+      "pascalCase": "",
+      "kebabCase": "",
+      "snakeCase": "",
+      "displayName": ""
+    },
     "defaultBranch": "main",
     "remoteUrl": ""
   },
   "git": {
-    "provider": "github",
+    "provider": "",
     "branches": {
       "main": "main",
       "develop": "develop"
@@ -21,9 +29,11 @@
     "enabled": true,
     "mode": "organized",
     "structure": {
-      "features": "../features",
-      "releases": "../releases",
-      "hotfixes": "../hotfixes"
+      "main": "",
+      "develop": "",
+      "features": "",
+      "releases": "",
+      "hotfixes": ""
     }
   },
   "versioning": {

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,16 +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",
+  "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": []
 }
 ```
+
+> **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>
@@ -214,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