fraim-framework 2.0.30 → 2.0.34

package/registry/scripts/prep-issue.sh

@@ -1,468 +1,468 @@
-#!/bin/bash
-
-set -e  # Exit on any error
-
-# Default flags (can be overridden by command line)
-SKIP_INSTALL=false
-SKIP_SERENA=true
-SKIP_EDITOR=true
-USE_DEFAULT_BRANCH=false
-
-# Function to display usage
-usage() {
-    echo "Usage: $0 <issue_number> [editor] [flags]"
-    echo "Example: $0 123"
-    echo "Example: $0 123 windsurf"
-    echo "Example: $0 123 claude --skip-install"
-    echo "Example: $0 123 cursor --use-default --skip-serena"
-    echo ""
-    echo "Editor options: windsurf, claude, claudecode, cursor (default)"
-    echo "If no editor specified, will try to detect from GitHub issue labels"
-    echo ""
-    echo "Flags:"
-    echo "  --skip-install    Skip npm install step"
-    echo "  --skip-serena     Skip Serena indexing step"
-    echo "  --skip-editor     Skip opening editor"
-    echo "  --use-default     Force branch creation from default branch (ignore current branch)"
-    echo "  --help           Show this help message"
-    exit 1
-}
-
-# Function to get editor from GitHub issue labels
-get_editor_from_issue() {
-    local issue_num=$1
-    
-    # Try to get the issue labels using GitHub CLI or curl
-    if command -v gh &> /dev/null; then
-        # Use GitHub CLI if available
-        local labels=$(gh issue view $issue_num -R "$REPO_OWNER/$REPO_NAME" --json labels --jq '.labels[].name' 2>/dev/null)
-    else
-        # Fallback to curl (requires GitHub token in GITHUB_TOKEN env var)
-        if [ -n "$GITHUB_TOKEN" ]; then
-            local labels=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
-                "https://api.github.com/repos/$REPO_OWNER/$REPO_NAME/issues/$issue_num" \
-                | grep -o '"name":"ai-agent:[^"]*"' | sed 's/"name":"ai-agent://' | sed 's/"//' 2>/dev/null)
-        else
-            echo "Warning: No GitHub CLI or GITHUB_TOKEN found. Cannot auto-detect editor from issue labels." >&2
-            return 1
-        fi
-    fi
-    
-    # Look for ai-agent labels
-    for label in $labels; do
-        if [[ $label == ai-agent:* ]]; then
-            local editor=${label#ai-agent:}
-            echo "Found ai-agent label: $label -> editor: $editor" >&2
-            echo "$editor"
-            return 0
-        fi
-    done
-    
-    echo "No ai-agent label found in issue #$issue_num, will continue without editor" >&2
-    return 0
-}
-
-# Parse command line arguments
-if [ $# -eq 0 ]; then
-    echo "Error: Issue number is required"
-    usage
-fi
-
-ISSUE_NUMBER=$1
-EDITOR=""  # Will be set later if not provided
-
-# Parse remaining arguments (editor and flags)
-shift 1  # Remove issue_number
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        --skip-install)
-            SKIP_INSTALL=true
-            shift
-            ;;
-        --skip-serena)
-            SKIP_SERENA=true
-            shift
-            ;;
-        --skip-editor)
-            SKIP_EDITOR=true
-            shift
-            ;;
-        --use-default)
-            USE_DEFAULT_BRANCH=true
-            shift
-            ;;
-        --help)
-            usage
-            ;;
-        windsurf|claude|claudecode|cursor)
-            # Valid editor names
-            if [ -z "$EDITOR" ]; then
-                EDITOR="$1"
-            else
-                echo "Error: Multiple editors specified: $EDITOR and $1"
-                usage
-            fi
-            shift
-            ;;
-        *)
-            echo "Unknown argument: $1"
-            echo "Valid editors: windsurf, claude, claudecode, cursor"
-            echo "Valid flags: --skip-install, --skip-serena, --skip-editor, --use-default"
-            usage
-            ;;
-    esac
-done
-
-# Load repository config from config.json
-CONFIG_FILE=".fraim/config.json"
-if [ ! -f "$CONFIG_FILE" ]; then
-    echo "Error: Config file not found at $CONFIG_FILE" >&2
-    exit 1
-fi
-
-if ! command -v node &> /dev/null; then
-    echo "Error: node is required but not installed." >&2
-    exit 1
-fi
-
-# Extract values using node reading from stdin to avoid path issues
-NODE_SCRIPT="
-const fs = require('fs');
-try {
-    const input = fs.readFileSync(0, 'utf-8');
-    const config = JSON.parse(input);
-    
-    // Support both 'repository' (new) and 'git' (legacy/current) schemas
-    let repo = config.repository;
-    
-    if (!repo) {
-        if (config.git) {
-            repo = {
-                owner: config.git.repoOwner,
-                name: config.git.repoName,
-                url: config.git.repoUrl || \`https://github.com/\${config.git.repoOwner}/\${config.git.repoName}.git\`
-            };
-        }
-    }
-
-    if (!repo || !repo.owner || !repo.name || !repo.url) {
-        process.exit(1);
-    }
-    console.log(\`\${repo.owner}:\${repo.name}:\${repo.url}\`);
-} catch (e) {
-    process.exit(1);
-}
-"
-
-REPO_INFO=$(cat "$CONFIG_FILE" | node -e "$NODE_SCRIPT")
-if [ $? -ne 0 ]; then
-    echo "Error: Failed to parse repository config from $CONFIG_FILE" >&2
-    echo "Required: repository.owner, repository.name, repository.url" >&2
-    exit 1
-fi
-
-# Split the result into variables
-IFS=':' read -r REPO_OWNER REPO_NAME REPO_URL <<< "$REPO_INFO"
-
-echo "Repository Configuration:"
-echo "  Owner: $REPO_OWNER"
-echo "  Name:  $REPO_NAME"
-echo "  URL:   $REPO_URL"
-echo
-
-echo "=== $REPO_NAME - Issue Preparation ==="
-echo "Preparing for Issue #$ISSUE_NUMBER"
-echo
-
-# Auto-detect editor from GitHub issue labels if not provided
-if [ -z "$EDITOR" ]; then
-    echo "No editor specified, attempting to detect from GitHub issue labels..."
-    echo "Fetching issue #$ISSUE_NUMBER labels from GitHub..."
-    DETECTED_EDITOR=$(get_editor_from_issue $ISSUE_NUMBER)
-    if [ $? -eq 0 ] && [ -n "$DETECTED_EDITOR" ]; then
-        EDITOR="$DETECTED_EDITOR"
-        echo "Auto-detected editor: $EDITOR"
-    else
-        EDITOR="cursor"  # Default fallback
-        echo "Using default editor: $EDITOR"
-    fi
-else
-    echo "Using specified editor: $EDITOR"
-fi
-
-# Step 1: Capture current branch BEFORE cloning
-echo "Step 1: Determining base branch from current repository..."
-
-# Determine base branch from the ORIGINAL repository (before cloning)
-if [ "$USE_DEFAULT_BRANCH" = true ]; then
-    # Detect the default branch
-    DEFAULT_BRANCH=""
-    for candidate in main master develop; do
-        if git ls-remote --exit-code --heads "$REPO_URL" "$candidate" >/dev/null 2>&1; then
-            DEFAULT_BRANCH="$candidate"
-            echo "✓ Detected default branch: $DEFAULT_BRANCH"
-            break
-        fi
-    done
-    
-    # Fallback to master if nothing else worked
-    if [ -z "$DEFAULT_BRANCH" ]; then
-        DEFAULT_BRANCH="master"
-        echo "⚠️  Could not detect default branch, defaulting to: $DEFAULT_BRANCH"
-    fi
-    
-    BASE_BRANCH="$DEFAULT_BRANCH"
-    echo "Using detected default branch as base: $BASE_BRANCH (--use-default flag)"
-else
-    # Get current branch from the original repo
-    ORIGINAL_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
-    
-    if [ -z "$ORIGINAL_BRANCH" ]; then
-        echo "Warning: Detached HEAD detected in original repo, falling back to default branch detection"
-        
-        # Detect the default branch
-        DEFAULT_BRANCH=""
-        for candidate in main master develop; do
-            if git ls-remote --exit-code --heads "$REPO_URL" "$candidate" >/dev/null 2>&1; then
-                DEFAULT_BRANCH="$candidate"
-                echo "✓ Detected default branch: $DEFAULT_BRANCH"
-                break
-            fi
-        done
-        
-        # Fallback to master if nothing else worked
-        if [ -z "$DEFAULT_BRANCH" ]; then
-            DEFAULT_BRANCH="master"
-            echo "⚠️  Could not detect default branch, defaulting to: $DEFAULT_BRANCH"
-        fi
-        
-        BASE_BRANCH="$DEFAULT_BRANCH"
-    else
-        BASE_BRANCH="$ORIGINAL_BRANCH"
-        echo "Using current branch from original repo as base: $BASE_BRANCH"
-    fi
-fi
-
-echo "Issue number = $ISSUE_NUMBER, Editor = $EDITOR, Base branch = $BASE_BRANCH"
-echo
-
-# Step 2: Clone the repo
-echo "Step 2: Cloning repository..."
-
-# Get current workspace path
-CURRENT_WORKSPACE=$(pwd)
-echo "Current workspace: $CURRENT_WORKSPACE"
-
-# Change to parent directory
-echo "Changing to parent directory..."
-cd ..
-PARENT_DIR=$(pwd)
-echo "Parent directory: $PARENT_DIR"
-
-# Define clone directory name
-CLONE_DIR="$REPO_NAME - Issue $ISSUE_NUMBER"
-CLONE_PATH="$PARENT_DIR/$CLONE_DIR"
-
-# Check if directory already exists
-if [ -d "$CLONE_PATH" ]; then
-    echo "Warning: Directory '$CLONE_PATH' already exists"
-    read -p "Do you want to remove it and re-clone? (y/N): " -n 1 -r
-    echo
-    if [[ $REPLY =~ ^[Yy]$ ]]; then
-        echo "Removing existing directory..."
-        rm -rf "$CLONE_PATH"
-    else
-        echo "Aborting. Please remove the existing directory manually or choose a different issue number."
-        exit 1
-    fi
-fi
-
-# Clone the repository
-echo "Cloning to: $CLONE_PATH"
-git clone "$REPO_URL" "$CLONE_DIR"
-
-# Change into the cloned repository
-cd "$CLONE_DIR"
-echo "Changed into cloned repository: $(pwd)"
-
-echo
-echo "Step 3: Safety Checklist Verification"
-echo "====================================="
-
-# Safety checklist verification
-echo -n "✓ Confirmed current workspace path with pwd: "
-pwd
-
-echo -n "✓ Verified we are in the cloned repository: "
-if [[ "$(pwd)" = "$CLONE_PATH" ]]; then
-    echo "YES"
-else
-    echo "NO - ERROR!"
-    exit 1
-fi
-
-echo -n "✓ Successfully changed into cloned repository: "
-if [ -d ".git" ]; then
-    echo "YES"
-else
-    echo "NO - ERROR!"
-    exit 1
-fi
-
-echo
-echo "🎉 Huzzah! Issue #$ISSUE_NUMBER preparation completed successfully!"
-echo "Repository cloned to: $(pwd)"
-echo
-
-# Step 4: Create and checkout the feature branch
-echo "Step 4: Creating and checking out feature branch..."
-
-# Get issue title for branch naming
-ISSUE_TITLE=$(gh issue view $ISSUE_NUMBER -R "$REPO_OWNER/$REPO_NAME" --json title --jq '.title' 2>/dev/null || echo "issue-$ISSUE_NUMBER")
-BRANCH_NAME="feature/${ISSUE_NUMBER}-$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-\|-$//g')"
-
-echo "Issue title: $ISSUE_TITLE"
-echo "Branch name: $BRANCH_NAME"
-echo "Base branch (from original repo): $BASE_BRANCH"
-
-# Create and checkout the branch
-if git show-ref --verify --quiet refs/heads/$BRANCH_NAME; then
-    echo "Branch $BRANCH_NAME already exists locally, checking it out..."
-    git checkout $BRANCH_NAME
-    git pull origin $BRANCH_NAME 2>/dev/null || echo "No remote branch to pull from"
-else
-    echo "Creating new branch $BRANCH_NAME from $BASE_BRANCH..."
-    
-    # Ensure we're on the base branch and it's up to date
-    git checkout $BASE_BRANCH
-    git pull origin $BASE_BRANCH 2>/dev/null || echo "Warning: Could not update $BASE_BRANCH from remote"
-    
-    # Create the new branch
-    git checkout -b $BRANCH_NAME
-    
-    # Push branch without any commits
-    # PR will be created by phase-change.yml when a phase label is applied
-    echo "Pushing empty branch to origin..."
-    git push -u origin $BRANCH_NAME
-fi
-
-echo "✓ Successfully on branch: $BRANCH_NAME (created from: $BASE_BRANCH)"
-
-# Install dependencies (optional)
-if [ "$SKIP_INSTALL" = false ]; then
-    echo "Installing npm dependencies..."
-    npm install
-    if [ $? -eq 0 ]; then
-        echo "✓ npm install completed successfully"
-    else
-        echo "⚠️  npm install failed - you may need to run it manually"
-    fi
-else
-    echo "⏭️  Skipping npm install (--skip-install flag)"
-fi
-
-# Step 5: Branch Ready for Phase Workflow
-echo "Step 5: Branch ready for phase workflow..."
-echo "✓ Branch $BRANCH_NAME created and pushed (no commits yet)"
-echo "✓ PR will be created when you apply a phase label to the issue"
-echo "   (phase:spec, phase:design, phase:tests, or phase:impl)"
-
-# Step 6: Index the codebase with Serena (optional)
-if [ "$SKIP_SERENA" = false ]; then
-    echo "Step 6: Indexing codebase with Serena..."
-    echo "Running: uvx --from git+https://github.com/oraios/serena serena project index"
-    
-    if command -v uvx &> /dev/null; then
-        uvx --from git+https://github.com/oraios/serena serena project index
-        if [ $? -eq 0 ]; then
-            echo "✓ Serena indexing completed successfully"
-        else
-            echo "⚠️  Serena indexing failed, but continuing..."
-        fi
-    else
-        echo "⚠️  uvx command not found, skipping Serena indexing"
-        echo "   You may want to install uvx or run the indexing manually"
-    fi
-else
-    echo "⏭️  Skipping Serena indexing (--skip-serena flag)"
-fi
-
-# Step 7: Open the specified editor in the new directory (optional)
-if [ "$SKIP_EDITOR" = false ]; then
-    echo "Step 7: Opening $EDITOR in the new workspace..."
-    echo "Opening: $(pwd)"
-    
-    # Open the specified editor
-    case $EDITOR in
-        windsurf)
-            if command -v windsurf &> /dev/null; then
-                echo "Opening with 'windsurf' command..."
-                windsurf .
-            else
-                echo "Could not find 'windsurf' command."
-                echo "Please manually open Windsurf in: $(pwd)"
-            fi
-            ;;
-        claude|claudecode)
-            if command -v claude &> /dev/null; then
-                echo "Opening with 'claude' command..."
-                claude --dangerously-skip-permissions .
-            else
-                echo "Could not find 'claude' command."
-                echo "Please manually open Claude in: $(pwd)"
-            fi
-            ;;
-        cursor)
-            if command -v cursor &> /dev/null; then
-                echo "Opening with 'cursor' command..."
-                cursor .
-            elif command -v code &> /dev/null; then
-                echo "Opening with 'code' command (VS Code fallback)..."
-                code .
-            else
-                echo "Could not find 'cursor' or 'code' command."
-                echo "Please manually open Cursor in: $(pwd)"
-            fi
-            ;;
-        *)
-            echo "Unknown editor: $EDITOR"
-            echo "Supported editors: windsurf, claude, claudecode, cursor"
-            echo "Please manually open your editor in: $(pwd)"
-            ;;
-    esac
-else
-    echo "⏭️  Skipping editor launch (--skip-editor flag)"
-    echo "Manually open your editor in: $(pwd)"
-fi
-
-echo
-echo "🎉 Setup Complete! Ready for agent workflow."
-echo
-echo "What was prepared:"
-echo "- ✅ Repository cloned and ready"
-echo "- ✅ Branch created: $BRANCH_NAME (from: $BASE_BRANCH)"
-echo "- ✅ Branch checked out and pushed"
-if [ "$SKIP_INSTALL" = false ]; then
-    echo "- ✅ Dependencies installed"
-else
-    echo "- ⏭️  Dependencies skipped"
-fi
-if [ "$SKIP_SERENA" = false ]; then
-    echo "- ✅ Codebase indexed with Serena"
-else
-    echo "- ⏭️  Serena indexing skipped"
-fi
-if [ "$SKIP_EDITOR" = false ]; then
-    echo "- ✅ Editor opened: $EDITOR"
-else
-    echo "- ⏭️  Editor launch skipped"
-fi
-echo
-echo "Agent workflow:"
-echo "1. Agent can start working immediately in this environment"
-echo "2. No need to create branches - already done!"
-echo "3. AGENT: Before starting work, you MUST read all documents in the retrospectives/ folder to learn from previous issues and avoid repeating mistakes."
-echo "4. Agent labels the issue with the appropriate phase (e.g., phase:spec, phase:design)"
-echo "5. GitHub Actions will automatically create the PR when phase label is applied"
-echo "6. Agent can commit and push changes directly"
-echo "7. GitHub Actions will update the PR when phase changes"
+#!/bin/bash
+
+set -e  # Exit on any error
+
+# Default flags (can be overridden by command line)
+SKIP_INSTALL=false
+SKIP_SERENA=true
+SKIP_EDITOR=true
+USE_DEFAULT_BRANCH=true
+
+# Function to display usage
+usage() {
+    echo "Usage: $0 <issue_number> [editor] [flags]"
+    echo "Example: $0 123"
+    echo "Example: $0 123 windsurf"
+    echo "Example: $0 123 claude --skip-install"
+    echo "Example: $0 123 cursor --use-default --skip-serena"
+    echo ""
+    echo "Editor options: windsurf, claude, claudecode, cursor (default)"
+    echo "If no editor specified, will try to detect from GitHub issue labels"
+    echo ""
+    echo "Flags:"
+    echo "  --skip-install    Skip npm install step"
+    echo "  --skip-serena     Skip Serena indexing step"
+    echo "  --skip-editor     Skip opening editor"
+    echo "  --use-default     Force branch creation from default branch (ignore current branch)"
+    echo "  --help           Show this help message"
+    exit 1
+}
+
+# Function to get editor from GitHub issue labels
+get_editor_from_issue() {
+    local issue_num=$1
+    
+    # Try to get the issue labels using GitHub CLI or curl
+    if command -v gh &> /dev/null; then
+        # Use GitHub CLI if available
+        local labels=$(gh issue view $issue_num -R "$REPO_OWNER/$REPO_NAME" --json labels --jq '.labels[].name' 2>/dev/null)
+    else
+        # Fallback to curl (requires GitHub token in GITHUB_TOKEN env var)
+        if [ -n "$GITHUB_TOKEN" ]; then
+            local labels=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
+                "https://api.github.com/repos/$REPO_OWNER/$REPO_NAME/issues/$issue_num" \
+                | grep -o '"name":"ai-agent:[^"]*"' | sed 's/"name":"ai-agent://' | sed 's/"//' 2>/dev/null)
+        else
+            echo "Warning: No GitHub CLI or GITHUB_TOKEN found. Cannot auto-detect editor from issue labels." >&2
+            return 1
+        fi
+    fi
+    
+    # Look for ai-agent labels
+    for label in $labels; do
+        if [[ $label == ai-agent:* ]]; then
+            local editor=${label#ai-agent:}
+            echo "Found ai-agent label: $label -> editor: $editor" >&2
+            echo "$editor"
+            return 0
+        fi
+    done
+    
+    echo "No ai-agent label found in issue #$issue_num, will continue without editor" >&2
+    return 0
+}
+
+# Parse command line arguments
+if [ $# -eq 0 ]; then
+    echo "Error: Issue number is required"
+    usage
+fi
+
+ISSUE_NUMBER=$1
+EDITOR=""  # Will be set later if not provided
+
+# Parse remaining arguments (editor and flags)
+shift 1  # Remove issue_number
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --skip-install)
+            SKIP_INSTALL=true
+            shift
+            ;;
+        --skip-serena)
+            SKIP_SERENA=true
+            shift
+            ;;
+        --skip-editor)
+            SKIP_EDITOR=true
+            shift
+            ;;
+        --use-default)
+            USE_DEFAULT_BRANCH=true
+            shift
+            ;;
+        --help)
+            usage
+            ;;
+        windsurf|claude|claudecode|cursor)
+            # Valid editor names
+            if [ -z "$EDITOR" ]; then
+                EDITOR="$1"
+            else
+                echo "Error: Multiple editors specified: $EDITOR and $1"
+                usage
+            fi
+            shift
+            ;;
+        *)
+            echo "Unknown argument: $1"
+            echo "Valid editors: windsurf, claude, claudecode, cursor"
+            echo "Valid flags: --skip-install, --skip-serena, --skip-editor, --use-default"
+            usage
+            ;;
+    esac
+done
+
+# Load repository config from config.json
+CONFIG_FILE=".fraim/config.json"
+if [ ! -f "$CONFIG_FILE" ]; then
+    echo "Error: Config file not found at $CONFIG_FILE" >&2
+    exit 1
+fi
+
+if ! command -v node &> /dev/null; then
+    echo "Error: node is required but not installed." >&2
+    exit 1
+fi
+
+# Extract values using node reading from stdin to avoid path issues
+NODE_SCRIPT="
+const fs = require('fs');
+try {
+    const input = fs.readFileSync(0, 'utf-8');
+    const config = JSON.parse(input);
+    
+    // Support both 'repository' (new) and 'git' (legacy/current) schemas
+    let repo = config.repository;
+    
+    if (!repo) {
+        if (config.git) {
+            repo = {
+                owner: config.git.repoOwner,
+                name: config.git.repoName,
+                url: config.git.repoUrl || \`https://github.com/\${config.git.repoOwner}/\${config.git.repoName}.git\`
+            };
+        }
+    }
+
+    if (!repo || !repo.owner || !repo.name || !repo.url) {
+        process.exit(1);
+    }
+    console.log(\`\${repo.owner}:\${repo.name}:\${repo.url}\`);
+} catch (e) {
+    process.exit(1);
+}
+"
+
+REPO_INFO=$(cat "$CONFIG_FILE" | node -e "$NODE_SCRIPT")
+if [ $? -ne 0 ]; then
+    echo "Error: Failed to parse repository config from $CONFIG_FILE" >&2
+    echo "Required: repository.owner, repository.name, repository.url" >&2
+    exit 1
+fi
+
+# Split the result into variables
+IFS=':' read -r REPO_OWNER REPO_NAME REPO_URL <<< "$REPO_INFO"
+
+echo "Repository Configuration:"
+echo "  Owner: $REPO_OWNER"
+echo "  Name:  $REPO_NAME"
+echo "  URL:   $REPO_URL"
+echo
+
+echo "=== $REPO_NAME - Issue Preparation ==="
+echo "Preparing for Issue #$ISSUE_NUMBER"
+echo
+
+# Auto-detect editor from GitHub issue labels if not provided
+if [ -z "$EDITOR" ]; then
+    echo "No editor specified, attempting to detect from GitHub issue labels..."
+    echo "Fetching issue #$ISSUE_NUMBER labels from GitHub..."
+    DETECTED_EDITOR=$(get_editor_from_issue $ISSUE_NUMBER)
+    if [ $? -eq 0 ] && [ -n "$DETECTED_EDITOR" ]; then
+        EDITOR="$DETECTED_EDITOR"
+        echo "Auto-detected editor: $EDITOR"
+    else
+        EDITOR="cursor"  # Default fallback
+        echo "Using default editor: $EDITOR"
+    fi
+else
+    echo "Using specified editor: $EDITOR"
+fi
+
+# Step 1: Capture current branch BEFORE cloning
+echo "Step 1: Determining base branch from current repository..."
+
+# Determine base branch from the ORIGINAL repository (before cloning)
+if [ "$USE_DEFAULT_BRANCH" = true ]; then
+    # Detect the default branch
+    DEFAULT_BRANCH=""
+    for candidate in main master develop; do
+        if git ls-remote --exit-code --heads "$REPO_URL" "$candidate" >/dev/null 2>&1; then
+            DEFAULT_BRANCH="$candidate"
+            echo "✓ Detected default branch: $DEFAULT_BRANCH"
+            break
+        fi
+    done
+    
+    # Fallback to master if nothing else worked
+    if [ -z "$DEFAULT_BRANCH" ]; then
+        DEFAULT_BRANCH="master"
+        echo "⚠️  Could not detect default branch, defaulting to: $DEFAULT_BRANCH"
+    fi
+    
+    BASE_BRANCH="$DEFAULT_BRANCH"
+    echo "Using detected default branch as base: $BASE_BRANCH (--use-default flag)"
+else
+    # Get current branch from the original repo
+    ORIGINAL_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+    
+    if [ -z "$ORIGINAL_BRANCH" ]; then
+        echo "Warning: Detached HEAD detected in original repo, falling back to default branch detection"
+        
+        # Detect the default branch
+        DEFAULT_BRANCH=""
+        for candidate in main master develop; do
+            if git ls-remote --exit-code --heads "$REPO_URL" "$candidate" >/dev/null 2>&1; then
+                DEFAULT_BRANCH="$candidate"
+                echo "✓ Detected default branch: $DEFAULT_BRANCH"
+                break
+            fi
+        done
+        
+        # Fallback to master if nothing else worked
+        if [ -z "$DEFAULT_BRANCH" ]; then
+            DEFAULT_BRANCH="master"
+            echo "⚠️  Could not detect default branch, defaulting to: $DEFAULT_BRANCH"
+        fi
+        
+        BASE_BRANCH="$DEFAULT_BRANCH"
+    else
+        BASE_BRANCH="$ORIGINAL_BRANCH"
+        echo "Using current branch from original repo as base: $BASE_BRANCH"
+    fi
+fi
+
+echo "Issue number = $ISSUE_NUMBER, Editor = $EDITOR, Base branch = $BASE_BRANCH"
+echo
+
+# Step 2: Clone the repo
+echo "Step 2: Cloning repository..."
+
+# Get current workspace path
+CURRENT_WORKSPACE=$(pwd)
+echo "Current workspace: $CURRENT_WORKSPACE"
+
+# Change to parent directory
+echo "Changing to parent directory..."
+cd ..
+PARENT_DIR=$(pwd)
+echo "Parent directory: $PARENT_DIR"
+
+# Define clone directory name
+CLONE_DIR="$REPO_NAME - Issue $ISSUE_NUMBER"
+CLONE_PATH="$PARENT_DIR/$CLONE_DIR"
+
+# Check if directory already exists
+if [ -d "$CLONE_PATH" ]; then
+    echo "Warning: Directory '$CLONE_PATH' already exists"
+    read -p "Do you want to remove it and re-clone? (y/N): " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        echo "Removing existing directory..."
+        rm -rf "$CLONE_PATH"
+    else
+        echo "Aborting. Please remove the existing directory manually or choose a different issue number."
+        exit 1
+    fi
+fi
+
+# Clone the repository
+echo "Cloning to: $CLONE_PATH"
+git clone "$REPO_URL" "$CLONE_DIR"
+
+# Change into the cloned repository
+cd "$CLONE_DIR"
+echo "Changed into cloned repository: $(pwd)"
+
+echo
+echo "Step 3: Safety Checklist Verification"
+echo "====================================="
+
+# Safety checklist verification
+echo -n "✓ Confirmed current workspace path with pwd: "
+pwd
+
+echo -n "✓ Verified we are in the cloned repository: "
+if [[ "$(pwd)" = "$CLONE_PATH" ]]; then
+    echo "YES"
+else
+    echo "NO - ERROR!"
+    exit 1
+fi
+
+echo -n "✓ Successfully changed into cloned repository: "
+if [ -d ".git" ]; then
+    echo "YES"
+else
+    echo "NO - ERROR!"
+    exit 1
+fi
+
+echo
+echo "🎉 Huzzah! Issue #$ISSUE_NUMBER preparation completed successfully!"
+echo "Repository cloned to: $(pwd)"
+echo
+
+# Step 4: Create and checkout the feature branch
+echo "Step 4: Creating and checking out feature branch..."
+
+# Get issue title for branch naming
+ISSUE_TITLE=$(gh issue view $ISSUE_NUMBER -R "$REPO_OWNER/$REPO_NAME" --json title --jq '.title' 2>/dev/null || echo "issue-$ISSUE_NUMBER")
+BRANCH_NAME="feature/${ISSUE_NUMBER}-$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-\|-$//g')"
+
+echo "Issue title: $ISSUE_TITLE"
+echo "Branch name: $BRANCH_NAME"
+echo "Base branch (from original repo): $BASE_BRANCH"
+
+# Create and checkout the branch
+if git show-ref --verify --quiet refs/heads/$BRANCH_NAME; then
+    echo "Branch $BRANCH_NAME already exists locally, checking it out..."
+    git checkout $BRANCH_NAME
+    git pull origin $BRANCH_NAME 2>/dev/null || echo "No remote branch to pull from"
+else
+    echo "Creating new branch $BRANCH_NAME from $BASE_BRANCH..."
+    
+    # Ensure we're on the base branch and it's up to date
+    git checkout $BASE_BRANCH
+    git pull origin $BASE_BRANCH 2>/dev/null || echo "Warning: Could not update $BASE_BRANCH from remote"
+    
+    # Create the new branch
+    git checkout -b $BRANCH_NAME
+    
+    # Push branch without any commits
+    # PR will be created by phase-change.yml when a phase label is applied
+    echo "Pushing empty branch to origin..."
+    git push -u origin $BRANCH_NAME
+fi
+
+echo "✓ Successfully on branch: $BRANCH_NAME (created from: $BASE_BRANCH)"
+
+# Install dependencies (optional)
+if [ "$SKIP_INSTALL" = false ]; then
+    echo "Installing npm dependencies..."
+    npm install
+    if [ $? -eq 0 ]; then
+        echo "✓ npm install completed successfully"
+    else
+        echo "⚠️  npm install failed - you may need to run it manually"
+    fi
+else
+    echo "⏭️  Skipping npm install (--skip-install flag)"
+fi
+
+# Step 5: Branch Ready for Phase Workflow
+echo "Step 5: Branch ready for phase workflow..."
+echo "✓ Branch $BRANCH_NAME created and pushed (no commits yet)"
+echo "✓ PR will be created when you apply a phase label to the issue"
+echo "   (phase:spec, phase:design, phase:tests, or phase:impl)"
+
+# Step 6: Index the codebase with Serena (optional)
+if [ "$SKIP_SERENA" = false ]; then
+    echo "Step 6: Indexing codebase with Serena..."
+    echo "Running: uvx --from git+https://github.com/oraios/serena serena project index"
+    
+    if command -v uvx &> /dev/null; then
+        uvx --from git+https://github.com/oraios/serena serena project index
+        if [ $? -eq 0 ]; then
+            echo "✓ Serena indexing completed successfully"
+        else
+            echo "⚠️  Serena indexing failed, but continuing..."
+        fi
+    else
+        echo "⚠️  uvx command not found, skipping Serena indexing"
+        echo "   You may want to install uvx or run the indexing manually"
+    fi
+else
+    echo "⏭️  Skipping Serena indexing (--skip-serena flag)"
+fi
+
+# Step 7: Open the specified editor in the new directory (optional)
+if [ "$SKIP_EDITOR" = false ]; then
+    echo "Step 7: Opening $EDITOR in the new workspace..."
+    echo "Opening: $(pwd)"
+    
+    # Open the specified editor
+    case $EDITOR in
+        windsurf)
+            if command -v windsurf &> /dev/null; then
+                echo "Opening with 'windsurf' command..."
+                windsurf .
+            else
+                echo "Could not find 'windsurf' command."
+                echo "Please manually open Windsurf in: $(pwd)"
+            fi
+            ;;
+        claude|claudecode)
+            if command -v claude &> /dev/null; then
+                echo "Opening with 'claude' command..."
+                claude --dangerously-skip-permissions .
+            else
+                echo "Could not find 'claude' command."
+                echo "Please manually open Claude in: $(pwd)"
+            fi
+            ;;
+        cursor)
+            if command -v cursor &> /dev/null; then
+                echo "Opening with 'cursor' command..."
+                cursor .
+            elif command -v code &> /dev/null; then
+                echo "Opening with 'code' command (VS Code fallback)..."
+                code .
+            else
+                echo "Could not find 'cursor' or 'code' command."
+                echo "Please manually open Cursor in: $(pwd)"
+            fi
+            ;;
+        *)
+            echo "Unknown editor: $EDITOR"
+            echo "Supported editors: windsurf, claude, claudecode, cursor"
+            echo "Please manually open your editor in: $(pwd)"
+            ;;
+    esac
+else
+    echo "⏭️  Skipping editor launch (--skip-editor flag)"
+    echo "Manually open your editor in: $(pwd)"
+fi
+
+echo
+echo "🎉 Setup Complete! Ready for agent workflow."
+echo
+echo "What was prepared:"
+echo "- ✅ Repository cloned and ready"
+echo "- ✅ Branch created: $BRANCH_NAME (from: $BASE_BRANCH)"
+echo "- ✅ Branch checked out and pushed"
+if [ "$SKIP_INSTALL" = false ]; then
+    echo "- ✅ Dependencies installed"
+else
+    echo "- ⏭️  Dependencies skipped"
+fi
+if [ "$SKIP_SERENA" = false ]; then
+    echo "- ✅ Codebase indexed with Serena"
+else
+    echo "- ⏭️  Serena indexing skipped"
+fi
+if [ "$SKIP_EDITOR" = false ]; then
+    echo "- ✅ Editor opened: $EDITOR"
+else
+    echo "- ⏭️  Editor launch skipped"
+fi
+echo
+echo "Agent workflow:"
+echo "1. Agent can start working immediately in this environment"
+echo "2. No need to create branches - already done!"
+echo "3. AGENT: Before starting work, you MUST read all documents in the retrospectives/ folder to learn from previous issues and avoid repeating mistakes."
+echo "4. Agent labels the issue with the appropriate phase (e.g., phase:spec, phase:design)"
+echo "5. GitHub Actions will automatically create the PR when phase label is applied"
+echo "6. Agent can commit and push changes directly"
+echo "7. GitHub Actions will update the PR when phase changes"