1. OUTPUT START MESSAGE:

🎯 STARTING: Branch Manager
Operation: {operation}
Branch: {branch_name}
Base Branch: {base_branch}
───────────────────────────────────────

2. LOAD CONFIGURATION:

Load repo configuration to determine:

• Active handler platform (github|gitlab|bitbucket)
• Default base branch
• Protected branches list
• Repository settings

Use repo-common skill to load configuration.

3. VALIDATE INPUTS:

Branch Name Validation:

• Check branch_name is non-empty
• Validate branch name follows Git naming conventions
• Ensure branch name is not a protected branch name
• Check for invalid characters

Base Branch Validation:

• Verify base_branch exists
• Check base_branch is not in invalid state
• Ensure base_branch is not a protected branch being used unsafely

Worktree Mode Validation:

• If worktree=true, verify work_id is provided
• If work_id is missing when worktree=true, ERROR: "work_id required for worktree mode"

4. CHECK WORKTREE REGISTRY (if worktree=true):

# Check if worktree exists for this work_id
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORKTREE_CHECK_SCRIPT="$SCRIPT_DIR/scripts/check-worktree.sh"

WORKTREE_REUSED=false
if EXISTING_WORKTREE=$("$WORKTREE_CHECK_SCRIPT" "$WORK_ID" 2>/dev/null); then
    echo "✅ Found existing worktree for work_id $WORK_ID"
    echo "   Path: $EXISTING_WORKTREE"

    # Update registry timestamp (reuse detected)
    "$SCRIPT_DIR/scripts/register-worktree.sh" "$WORK_ID" "$EXISTING_WORKTREE" "$BRANCH_NAME"

    # Switch to worktree directory
    cd "$EXISTING_WORKTREE"

    WORKTREE_REUSED=true
    WORKTREE_PATH="$EXISTING_WORKTREE"
else
    echo "🆕 No existing worktree found, will create new worktree"
fi

⚡ WORKFLOW DECISION POINT:

Note: Uses scripts/check-worktree.sh to check registry and validate worktree path. This script:

• Checks ~/.fractary/repo/worktrees.json for work_id mapping
• Validates worktree directory still exists
• Removes stale entries automatically
• Returns worktree path if valid, exits with code 1 if not

5. CHECK PROTECTED BRANCHES:

PROTECTED_BRANCHES = config.defaults.protected_branches
if branch_name in PROTECTED_BRANCHES:
    ERROR: "Cannot create branch with protected branch name: {branch_name}"
    EXIT CODE 10

6. INVOKE HANDLER:

Invoke the active source control handler skill.

IMPORTANT: You MUST use the Skill tool to invoke the handler. The handler skill name is constructed as follows:

1. Read the platform from config: config.handlers.source_control.active (e.g., "github")
2. Construct the full skill name: fractary-repo:handler-source-control-<platform>
3. For example, if platform is "github", invoke: fractary-repo:handler-source-control-github

DO NOT use any other handler name pattern. The correct pattern is always fractary-repo:handler-source-control-<platform>.

Branch Creation (if not reusing worktree): Use the Skill tool with:

• command: fractary-repo:handler-source-control-<platform> (where is from config)
• Pass parameters: {branch_name, base_branch, force, checkout: false} (checkout=false for worktree mode)

The handler will:

• Check if branch already exists
• Create branch from base branch
• Return branch creation details with commit SHA

Worktree Creation (if worktree=true and not reused):

# Create worktree using script
WORKTREE_PATH=$("$SCRIPT_DIR/scripts/create-worktree.sh" "$BRANCH_NAME" "$WORK_ID")

if [ $? -ne 0 ]; then
    echo "❌ Failed to create worktree"
    exit 1
fi

echo "✅ Worktree created: $WORKTREE_PATH"

# Register worktree in registry
"$SCRIPT_DIR/scripts/register-worktree.sh" "$WORK_ID" "$WORKTREE_PATH" "$BRANCH_NAME"

# Switch to worktree directory
cd "$WORKTREE_PATH"
echo "✅ Switched to worktree directory: $WORKTREE_PATH"

Note: Uses scripts/create-worktree.sh which:

• Creates worktree in .worktrees/ subfolder (within repo root)
• Truncates branch slugs > 80 chars (with hash for uniqueness)
• Returns worktree path on success
• Handles long path names gracefully

7. VALIDATE RESPONSE:

• Check handler returned success status (if branch was created)
• Verify branch was created (check Git status)
• Capture commit SHA of branch creation point
• If worktree mode: Confirm worktree directory exists and is accessible
• Confirm current directory is worktree (if worktree mode)

8. CACHE UPDATE (AUTOMATIC):

The handler script (create-branch.sh) automatically updates the status cache after checkout. No manual action needed.

What gets updated:

• Current branch name
• Issue ID (extracted from new branch name using pattern prefix/ID-description)
• PR number (empty for newly created branches)

Note: Cache update is handled by the handler script to ensure deterministic execution. The skill does not need to invoke cache updates separately.

9. OUTPUT COMPLETION MESSAGE:

If worktree reused:

✅ COMPLETED: Branch Manager
Operation: create-branch (worktree reused)
Work ID: {work_id}
Branch: {branch_name}
Worktree: {worktree_path} (reused existing)
Status Cache: ✅ Updated (status line now shows branch)
───────────────────────────────────────
Next: Continue workflow in existing worktree

If worktree created:

✅ COMPLETED: Branch Manager
Operation: create-branch (worktree created)
Work ID: {work_id}
Branch Created: {branch_name}
Base Branch: {base_branch}
Worktree: {worktree_path}
Commit SHA: {commit_sha}
Status Cache: ✅ Updated (status line now shows new branch)
───────────────────────────────────────
Next: Make changes in worktree and commit

If normal mode (no worktree):

✅ COMPLETED: Branch Manager
Operation: create-branch
Branch Created: {branch_name}
Base Branch: {base_branch}
Commit SHA: {commit_sha}
Status Cache: ✅ Updated (status line now shows new branch)
───────────────────────────────────────
Next: Make changes and use commit-creator skill to commit them