⚡ EXECUTION INSTRUCTIONS FOR CLAUDE

When this command is invoked, YOU (Claude) must execute these steps immediately: This is NOT documentation - these are COMMANDS to execute right now. Use TodoWrite to track progress through multi-phase workflows.

🚨 EXECUTION WORKFLOW

Phase 1: Execute Documented Workflow

Action Steps:

1. Review the reference documentation below and execute the detailed steps sequentially.

📋 REFERENCE DOCUMENTATION

/headless - Enhanced Planning + Headless Development

Purpose: Combine /handoff planning with /headless automation - creates detailed analysis then generates copy-paste command for headless execution

Usage: /headless [prompt]

Enhanced Workflow:

1. Phase 1 - Planning (from /handoff):

   • Creates isolated git worktree with new branch
   • Generates detailed planning scratchpad with implementation plan
   • Analyzes requirements and creates step-by-step approach
   • Commits planning documentation and pushes branch

2. Phase 2 - Command Generation:

   • Builds comprehensive prompt with full context
   • Generates copy-pasteable headless command
   • User reviews plan and executes when ready

Implementation:

#!/bin/bash

# Get the prompt from arguments

PROMPT="$*"

if [ -z "$PROMPT" ]; then
    echo "❌ Error: No prompt provided"
    echo "Usage: /headless [prompt]"
    exit 1
fi

# Generate a unique branch name based on timestamp and prompt

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BRANCH_NAME="headless_${TIMESTAMP}"
WORKTREE_DIR="headless_${TIMESTAMP}"

echo "🚀 Creating headless development environment..."
echo "Branch: $BRANCH_NAME"
echo "Worktree: $WORKTREE_DIR"
echo "Prompt: $PROMPT"

# Determine the default branch dynamically

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')

# Create git worktree with new branch from the default branch

git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" "$DEFAULT_BRANCH"

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

# Change to worktree directory

cd "$WORKTREE_DIR"

echo "📁 Working in: $(pwd)"
echo "🎯 Running Claude Code headlessly..."

# Run Claude Code in headless mode with stream monitoring

claude -p "$PROMPT" --output-format stream-json --verbose --dangerously-skip-permissions

if [ $? -ne 0 ]; then
    echo "❌ Error: Claude Code execution failed"
    cd ..
    git worktree remove "$WORKTREE_DIR"
    exit 1
fi

echo "✅ Claude Code execution completed"
echo "🔄 Creating pull request..."

# Run /pr command to create PR

if [ -f ".claude/commands/pr.md" ] && [ -x "./claude_command_scripts/pr.sh" ]; then
    # Extract and run the PR creation logic
    ./claude_command_scripts/pr.sh
else
    echo "⚠️ /pr command or script not found or not executable, creating PR manually..."

    # Push the branch
    git push -u origin "$BRANCH_NAME"

    # Create PR using gh
    gh pr create --title "Headless: $(echo "$PROMPT" | cut -c1-50)..." --body "$(cat <<EOF

## Automated Headless Development

**Prompt**: $PROMPT

**Branch**: $BRANCH_NAME

**Generated**: $(date)

This PR was created automatically using the /headless command.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"
fi

echo "🎉 Headless development completed!"
echo "📂 Worktree location: $WORKTREE_DIR"
echo "🌿 Branch: $BRANCH_NAME"

# Return to original directory

cd ..

Enhanced Features:

• ✅ Detailed Planning: Creates comprehensive implementation plan (from /handoff)
• ✅ Isolated Environment: Separate git worktree prevents conflicts
• ✅ User Control: Review generated plan before execution
• ✅ Rich Context: Full prompt with specifications and requirements
• ✅ Copy-Paste Ready: Generated command with all context included
• ✅ Documentation: Planning scratchpad with step-by-step approach

Safety Features:

• Uses --dangerously-skip-permissions for true headless operation
• Creates isolated worktree to prevent conflicts with current work
• Automatic cleanup on failure
• Preserves original working directory

Example Usage:

/headless "Add user authentication system with login/logout functionality"
/headless "Fix the responsive design issues on mobile devices"
/headless "Implement automated testing for the payment processing module"

Example Output:

🚀 Enhanced Headless Development with Planning
Task: Add user authentication system
Branch: headless_20250718_143022
Worktree: headless_20250718_143022

📋 Phase 1: Creating Analysis and Planning
📁 Creating isolated worktree...
📁 Working in: /path/to/headless_20250718_143022
📋 Creating detailed planning scratchpad...

================================================================================
✅ PLANNING PHASE COMPLETE
================================================================================
📋 Planning file: roadmap/scratchpad_headless_20250718_143022.md
🌿 Branch: headless_20250718_143022 (pushed to remote)
📁 Worktree: /path/to/headless_20250718_143022

================================================================================
🤖 HEADLESS COMMAND READY (Copy & Paste)
================================================================================

claude -p "TASK: Add user authentication system

CONTEXT: Complete analysis and implementation plan available
WORKTREE: /path/to/headless_20250718_143022
BRANCH: headless_20250718_143022

SETUP: Already in isolated worktree with clean branch
GOAL: Add user authentication system
IMPLEMENTATION: See detailed plan below

FILES TO MODIFY: See specific file list in implementation section
SUCCESS CRITERIA: All requirements met with tests passing
TIMELINE: Implement according to step-by-step plan

FULL SPECIFICATION: /path/to/headless_20250718_143022/roadmap/scratchpad_headless_20250718_143022.md

START: Implement the detailed plan below" --output-format stream-json --verbose --dangerously-skip-permissions

================================================================================
📋 Next Steps:
1. Review the generated plan in: roadmap/scratchpad_headless_20250718_143022.md
2. Modify the plan if needed (add details, adjust approach)
3. Copy and paste the command above when ready to execute
4. The command will run Claude in headless mode in this worktree

✅ Ready for headless execution!

Integration with Orchestration System:

• Follows the proven agent architecture patterns from CLAUDE.md
• Uses the same headless flags that prevent interactive prompts
• Implements git worktree isolation for conflict prevention
• Provides stream-json monitoring for cost and progress tracking