@atlashub/smartstack-cli 1.35.0 → 1.37.0

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

@@ -16,9 +16,12 @@ Create tags for releases/hotfixes, merge back to develop, clean up worktree and
 
 ## EXECUTION SEQUENCE:
 
-### 1. Determine Branch Context
+### 1. Load Config and Determine Branch Context
 
 ```bash
+# Load GitFlow config (sets GF_* variables)
+read_gitflow_config || { echo "❌ Run /gitflow init first."; exit 1; }
+
 # Get current or specified branch
 BRANCH=${1:-$(git rev-parse --abbrev-ref HEAD)}
 BRANCH_TYPE=$(echo $BRANCH | cut -d'/' -f1)
@@ -27,8 +30,8 @@ BRANCH_NAME=$(echo $BRANCH | cut -d'/' -f2)
 # Validate branch type
 case "$BRANCH_TYPE" in
   feature|release|hotfix) ;;
-  main|develop)
-    echo "❌ Cannot finish main or develop branch"
+  $GF_MAIN_BRANCH|$GF_DEVELOP_BRANCH)
+    echo "❌ Cannot finish $GF_MAIN_BRANCH or $GF_DEVELOP_BRANCH branch"
     STOP
     ;;
   *)
@@ -46,12 +49,12 @@ git fetch origin
 # Check if branch was merged
 case "$BRANCH_TYPE" in
   feature)
-    MERGED=$(git branch -r --merged origin/develop | grep "$BRANCH" | wc -l)
-    TARGET="develop"
+    MERGED=$(git branch -r --merged origin/$GF_DEVELOP_BRANCH | grep "$BRANCH" | wc -l)
+    TARGET="$GF_DEVELOP_BRANCH"
     ;;
   release|hotfix)
-    MERGED=$(git branch -r --merged origin/main | grep "$BRANCH" | wc -l)
-    TARGET="main"
+    MERGED=$(git branch -r --merged origin/$GF_MAIN_BRANCH | grep "$BRANCH" | wc -l)
+    TARGET="$GF_MAIN_BRANCH"
     ;;
 esac
 
@@ -74,8 +77,8 @@ esac
 
 ```bash
 if [ "$BRANCH_TYPE" = "release" ] || [ "$BRANCH_TYPE" = "hotfix" ]; then
-  # Get version
-  VERSION=$(grep -oP '"current":\s*"\K[^"]+' .claude/gitflow/config.json 2>/dev/null)
+  # Get version from config (already loaded)
+  VERSION="$GF_VERSION"
 
   # For hotfix, increment patch
   if [ "$BRANCH_TYPE" = "hotfix" ]; then
@@ -95,8 +98,8 @@ if [ "$BRANCH_TYPE" = "release" ] || [ "$BRANCH_TYPE" = "hotfix" ]; then
   }
 
   # Create tag on main
-  git checkout main
-  git pull origin main
+  git checkout $GF_MAIN_BRANCH
+  git pull origin $GF_MAIN_BRANCH
   git tag -a "$TAG_NAME" -m "$BRANCH_TYPE: $BRANCH_NAME"
   git push origin "$TAG_NAME"
 
@@ -108,13 +111,13 @@ fi
 
 ```bash
 if [ "$BRANCH_TYPE" = "release" ] || [ "$BRANCH_TYPE" = "hotfix" ]; then
-  echo "Merging $TAG_NAME back to develop..."
+  echo "Merging $TAG_NAME back to $GF_DEVELOP_BRANCH..."
 
-  git checkout develop
-  git pull origin develop
+  git checkout $GF_DEVELOP_BRANCH
+  git pull origin $GF_DEVELOP_BRANCH
 
   # Merge with merge commit (preserve history)
-  git merge main -m "Merge $TAG_NAME back to develop"
+  git merge $GF_MAIN_BRANCH -m "Merge $TAG_NAME back to $GF_DEVELOP_BRANCH"
 
   # Handle conflicts
   CONFLICTS=$(git diff --name-only --diff-filter=U | wc -l)
@@ -125,48 +128,55 @@ if [ "$BRANCH_TYPE" = "release" ] || [ "$BRANCH_TYPE" = "hotfix" ]; then
     # Options: resolve, abort
   }
 
-  git push origin develop
+  git push origin $GF_DEVELOP_BRANCH
 
   # CRITICAL: Verify push and update tracking refs
-  git fetch origin develop:refs/remotes/origin/develop --force --quiet
+  git fetch origin $GF_DEVELOP_BRANCH:refs/remotes/origin/$GF_DEVELOP_BRANCH --force --quiet
   LOCAL_SHA=$(git rev-parse HEAD)
-  REMOTE_SHA=$(git rev-parse origin/develop)
+  REMOTE_SHA=$(git rev-parse origin/$GF_DEVELOP_BRANCH)
   if [ "$LOCAL_SHA" = "$REMOTE_SHA" ]; then
     echo "✅ Push verified - local/remote in sync"
   else
     echo "⚠️ Push verification FAILED"
     echo "  Local:  $LOCAL_SHA"
     echo "  Remote: $REMOTE_SHA"
-    echo "  → Try: git push origin develop --force-with-lease"
+    echo "  → Try: git push origin $GF_DEVELOP_BRANCH --force-with-lease"
   fi
 
-  echo "✅ Merged back to develop"
+  echo "✅ Merged back to $GF_DEVELOP_BRANCH"
 fi
 ```
 
-### 5. Update Version (Release only)
+### 5. Update Version (Release and Hotfix)
 
 ```bash
-if [ "$BRANCH_TYPE" = "release" ]; then
-  # Increment minor version for next development
+if [ "$BRANCH_TYPE" = "release" ] || [ "$BRANCH_TYPE" = "hotfix" ]; then
   MAJOR=$(echo $VERSION | cut -d'.' -f1)
   MINOR=$(echo $VERSION | cut -d'.' -f2)
-  NEXT_VERSION="$MAJOR.$((MINOR + 1)).0"
+  PATCH=$(echo $VERSION | cut -d'.' -f3)
+
+  if [ "$BRANCH_TYPE" = "release" ]; then
+    # Release: increment minor, reset patch
+    NEXT_VERSION="$MAJOR.$((MINOR + 1)).0"
+  else
+    # Hotfix: increment patch (patch was already bumped for the tag, bump again for next dev)
+    NEXT_VERSION="$MAJOR.$MINOR.$((PATCH + 2))"
+  fi
 
-  # Update config
-  sed -i "s/\"current\": \"$VERSION\"/\"current\": \"$NEXT_VERSION\"/" .claude/gitflow/config.json
+  # Update config (using resolved config path)
+  sed -i "s/\"current\": \".*\"/\"current\": \"$NEXT_VERSION\"/" "$GF_CONFIG_FILE"
 
   # Update source files
   # csproj, package.json, etc.
 
   git add -A
   git commit -m "chore: bump version to $NEXT_VERSION for development"
-  git push origin develop
+  git push origin $GF_DEVELOP_BRANCH
 
   # CRITICAL: Verify push and update tracking refs
-  git fetch origin develop:refs/remotes/origin/develop --force --quiet
+  git fetch origin $GF_DEVELOP_BRANCH:refs/remotes/origin/$GF_DEVELOP_BRANCH --force --quiet
   LOCAL_SHA=$(git rev-parse HEAD)
-  REMOTE_SHA=$(git rev-parse origin/develop)
+  REMOTE_SHA=$(git rev-parse origin/$GF_DEVELOP_BRANCH)
   if [ "$LOCAL_SHA" = "$REMOTE_SHA" ]; then
     echo "✅ Push verified - local/remote in sync"
   else
@@ -182,14 +192,14 @@ fi
 ### 6. Clean Up Worktree
 
 ```bash
-# Find worktree for this branch
-WORKTREE_PATH=$(git worktree list | grep "$BRANCH" | awk '{print $1}')
+# Find worktree for this branch (use --porcelain for reliable parsing)
+WORKTREE_PATH=$(git worktree list --porcelain | grep -B2 "branch refs/heads/$BRANCH" | grep "^worktree " | sed 's/^worktree //')
 
 if [ -n "$WORKTREE_PATH" ] && [ -d "$WORKTREE_PATH" ]; then
   echo "Removing worktree: $WORKTREE_PATH"
 
-  # Make sure we're not in the worktree
-  cd $(git rev-parse --show-toplevel)
+  # Make sure we're not in the worktree directory
+  cd "$GF_DEVELOP_PATH" 2>/dev/null || cd "$(git rev-parse --show-toplevel)"
 
   git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || {
     rm -rf "$WORKTREE_PATH"

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

@@ -452,6 +452,7 @@ mkdir -p "$DEVELOP_PATH/.claude/gitflow/{plans,logs,cache,backup}"
   "version": "2.0.0",
   "repository": {
     "name": "{PROJECT_NAME}",
+    "rootFolder": "{ROOT_FOLDER}",
     "nameVariants": {
       "pascalCaseDot": "{PascalCase.Dot}",
       "pascalCase": "{PascalCase}",
@@ -459,7 +460,7 @@ mkdir -p "$DEVELOP_PATH/.claude/gitflow/{plans,logs,cache,backup}"
       "snakeCase": "{snake_case}",
       "displayName": "{Display Name}"
     },
-    "rootFolder": "{ROOT_FOLDER}",
+    "defaultBranch": "main",
     "remoteUrl": "{REPO_URL}"
   },
   "git": {
@@ -494,7 +495,8 @@ mkdir -p "$DEVELOP_PATH/.claude/gitflow/{plans,logs,cache,backup}"
   "efcore": {
     "enabled": true,
     "validateOnCommit": true,
-    "blockDestructive": true
+    "blockDestructive": true,
+    "migrationNaming": "{context}_v{version}_{sequence}_{Description}"
   },
   "workflow": {
     "push": {
@@ -504,6 +506,9 @@ mkdir -p "$DEVELOP_PATH/.claude/gitflow/{plans,logs,cache,backup}"
       "autoLabels": true,
       "requireReview": true
     }
+  },
+  "language": {
+    "code": "{GF_LANG}"
   }
 }
 ```

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

@@ -16,19 +16,33 @@ Run through review checklist and merge the pull request with appropriate strateg
 
 ## EXECUTION SEQUENCE:
 
-### 1. Load PR Context
+### 1. Load Config and PR Context
 
 ```bash
+# Load GitFlow config (sets GF_* variables)
+read_gitflow_config || { echo "❌ Run /gitflow init first."; exit 1; }
+
 CURRENT=$(git rev-parse --abbrev-ref HEAD)
-GIT_PROVIDER=$(grep -oP '"provider":\s*"\K[^"]+' .claude/gitflow/config.json 2>/dev/null || echo "github")
+GIT_PROVIDER="$GF_PROVIDER"
+
+# Try loading persisted PR state first
+CONFIG_DIR=$(dirname "$GF_CONFIG_FILE")
+PR_STATE_FILE="$CONFIG_DIR/cache/pr-state.json"
+if [ -f "$PR_STATE_FILE" ]; then
+  PR_NUMBER=$(grep -oP '"pr_number":\s*"\K[^"]+' "$PR_STATE_FILE" | head -1)
+  TARGET_BRANCH=$(grep -oP '"target_branch":\s*"\K[^"]+' "$PR_STATE_FILE" | head -1)
+  echo "✓ Loaded PR state from cache: PR #$PR_NUMBER → $TARGET_BRANCH"
+fi
 
-# Get PR number
-if [ "$GIT_PROVIDER" = "github" ]; then
-  PR_NUMBER=$(gh pr list --head "$CURRENT" --json number --jq '.[0].number')
-  PR_STATUS=$(gh pr view $PR_NUMBER --json state,mergeable,reviews --jq '.')
-elif [ "$GIT_PROVIDER" = "azuredevops" ]; then
-  PR_NUMBER=$(az repos pr list --source-branch "$CURRENT" --query "[0].pullRequestId" -o tsv)
-  PR_STATUS=$(az repos pr show --id $PR_NUMBER --query "{status:status,mergeStatus:mergeStatus}")
+# Fallback: query provider if no cached state
+if [ -z "$PR_NUMBER" ]; then
+  if [ "$GIT_PROVIDER" = "github" ]; then
+    PR_NUMBER=$(gh pr list --head "$CURRENT" --json number --jq '.[0].number')
+    PR_STATUS=$(gh pr view $PR_NUMBER --json state,mergeable,reviews --jq '.')
+  elif [ "$GIT_PROVIDER" = "azuredevops" ]; then
+    PR_NUMBER=$(az repos pr list --source-branch "$CURRENT" --query "[0].pullRequestId" -o tsv)
+    PR_STATUS=$(az repos pr show --id $PR_NUMBER --query "{status:status,mergeStatus:mergeStatus}")
+  fi
 fi
 
 [ -z "$PR_NUMBER" ] && {
@@ -125,7 +139,7 @@ case "$BRANCH_TYPE" in
   release|hotfix)
     MERGE_STRATEGY="merge"
     DELETE_BRANCH=true
-    MERGE_BACK="develop"
+    MERGE_BACK="$GF_DEVELOP_BRANCH"
     ;;
 esac
 ```

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,6 +2,7 @@
   "version": "2.0.0",
   "repository": {
     "name": "",
+    "rootFolder": "",
     "nameVariants": {
       "pascalCaseDot": "",
       "pascalCase": "",
@@ -13,7 +14,7 @@
     "remoteUrl": ""
   },
   "git": {
-    "provider": "github",
+    "provider": "",
     "branches": {
       "main": "main",
       "develop": "develop"
@@ -28,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,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>