/hybrid-complete

description: "Complete Hybrid Ralph task in worktree, verify all stories complete, commit code changes (excluding planning files), merge to target branch, and cleanup worktree directory. Can be run from any directory."

Hybrid Ralph - Complete Worktree Task

You are completing a Hybrid Ralph task in a worktree and merging it to the target branch.

Path Storage Modes

This command works with both new and legacy path storage modes:

New Mode (Default)

• Worktrees located in: `~/.plan-cascade/<project-id>/.worktree/` (Unix) or `%APPDATA%/plan-cascade/<project-id>/.worktree/` (Windows)
• State files in: `~/.plan-cascade/<project-id>/.state/`
• Cleanup removes files from user data directory

Legacy Mode

• Worktrees located in: `<project-root>/.worktree/`
• State files in project root
• Cleanup removes files from project root

The command auto-detects which mode is active based on `.planning-config.json` contents.

Step 1: Detect Current Location

Check if we're in a worktree or the root directory:

if [ -f ".planning-config.json" ]; then
    # We're in a worktree directory
    echo "Currently in worktree directory: $(pwd)"
    IN_WORKTREE=true
else
    # We're not in a worktree, check if there are any worktrees
    IN_WORKTREE=false

    # Check for worktrees
    WORKTREES=$(git worktree list 2>/dev/null | grep -v "\bare$" | wc -l)

    if [ "$WORKTREES" -eq 0 ]; then
        echo "ERROR: No worktrees found."
        echo "This command requires an existing hybrid worktree."
        echo ""
        echo "Create one first with:"
        echo "  /plan-cascade:hybrid-worktree <task-name> <branch> <description>"
        exit 1
    fi

    echo "Not in a worktree directory. Found $WORKTREES worktree(s):"
    echo ""
    git worktree list
    echo ""

    # Find all hybrid worktrees (check both new mode user directory and legacy project root)
    echo "Scanning for hybrid worktrees..."
    HYBRID_WORKTREES=()

    # Get worktree base directory from PathResolver (handles new vs legacy mode)
    WORKTREE_BASE=$(uv run python -c "from plan_cascade.state.path_resolver import PathResolver; from pathlib import Path; print(PathResolver(Path.cwd()).get_worktree_dir())" 2>/dev/null || echo ".worktree")

    while IFS= read -r line; do
        worktree_path=$(echo "$line" | awk '{print $1}')
        worktree_branch=$(echo "$line" | awk '{print $2}')

        # Check if this is a hybrid worktree
        if [ -f "$worktree_path/.planning-config.json" ]; then
            mode=$(jq -r '.mode // empty' "$worktree_path/.planning-config.json" 2>/dev/null)
            if [ "$mode" = "hybrid" ]; then
                task_name=$(jq -r '.task_name // empty' "$worktree_path/.planning-config.json" 2>/dev/null)
                HYBRID_WORKTREES+=("$worktree_path|$task_name|$worktree_branch")
            fi
        fi
    done < <(git worktree list 2>/dev/null | grep -v "\bare$")

    if [ ${#HYBRID_WORKTREES[@]} -eq 0 ]; then
        echo "ERROR: No hybrid worktrees found."
        echo "Found worktrees but none are in hybrid mode."
        exit 1
    fi

    echo "Found ${#HYBRID_WORKTREES[@]} hybrid worktree(s):"
    echo ""

    # Display options
    for i in "${!HYBRID_WORKTREES[@]}"; do
        IFS='|' read -r path name branch <<< "$i"
        echo "  [$((i+1))] $name"
        echo "      Path: $path"
        echo "      Branch: $branch"
        echo ""
    done

    # Ask user to select
    echo "Which worktree would you like to complete?"
    read -p "Enter number (or 0 to cancel): " selection

    if [ "$selection" = "0" ]; then
        echo "Cancelled."
        exit 0
    fi

    if [ "$selection" -lt 1 ] || [ "$selection" -gt ${#HYBRID_WORKTREES[@]} ]; then
        echo "Invalid selection."
        exit 1
    fi

    # Get the selected worktree
    selected="${HYBRID_WORKTREES[$((selection-1))]}"
    IFS='|' read -r WORKTREE_PATH TASK_NAME TASK_BRANCH <<< "$selected"

    echo ""
    echo "Selected: $TASK_NAME"
    echo "Navigating to worktree: $WORKTREE_PATH"

    # Change to worktree directory
    cd "$WORKTREE_PATH" || {
        echo "ERROR: Failed to navigate to worktree: $WORKTREE_PATH"
        exit 1
    }

    echo "✓ Now in worktree: $(pwd)"
    IN_WORKTREE=true
fi

Step 2: Verify Worktree Mode (if in worktree)

MODE=$(jq -r '.mode // empty' .planning-config.json 2>/dev/null || echo "")
if [ "$MODE" != "hybrid" ]; then
    echo "ERROR: Not in hybrid worktree mode."
    exit 1
fi

Step 3: Read Planning Config

TASK_NAME=$(jq -r '.task_name' .planning-config.json)
TASK_BRANCH=$(jq -r '.task_branch' .planning-config.json)
TARGET_BRANCH=$(jq -r '.target_branch' .planning-config.json)
WORKTREE_DIR=$(jq -r '.worktree_dir' .planning-config.json)
ROOT_DIR=$(jq -r '.root_dir' .planning-config.json)

# Allow override from args
OVERRIDE_TARGET="{{args|first arg or empty}}"
TARGET_FINAL="${OVERRIDE_TARGET:-$TARGET_BRANCH}"

Step 4: Verify All Stories Complete

Check if all stories in `prd.json` are marked complete in `progress.txt`:

# Count total stories in PRD
TOTAL_STORIES=$(jq '.stories | length' prd.json)

# Count completed stories in progress.txt
COMPLETE_STORIES=$(grep -c "\[COMPLETE\]" progress.txt 2>/dev/null || echo "0")

if [ "$COMPLETE_STORIES" -lt "$TOTAL_STORIES" ]; then
    echo "WARNING: Not all stories are complete"
    echo "Completed: $COMPLETE_STORIES / $TOTAL_STORIES"
    echo ""
    echo "Continue anyway? [y/N]"
    read -r response
    if [[ ! "$response" =~ ^[Yy]$ ]]; then
        echo "Aborted. Complete remaining stories first."
        exit 1
    fi
fi

Step 5: CRITICAL - Check for Uncommitted Code Changes

**IMPORTANT**: Planning files are NOT included in the commit. We check only actual code changes.

# Define planning files to exclude from commit
PLANNING_FILES=(
    "prd.json"
    "findings.md"
    "progress.txt"
    ".planning-config.json"
    ".agent-outputs/"
    "mega-findings.md"
    ".agent-s