claude-fsd 1.5.7 → 1.5.9

package/bin/claudefsd

@@ -173,7 +173,7 @@ open_with_editor() {
 # Check dependencies first
 check_dependencies
 
-# Function to check for updates (non-blocking)
+# Function to check for updates and auto-update if needed
 check_for_updates() {
     # Only check if we can reach npm registry quickly
     if timeout 2 npm view claude-fsd version >/dev/null 2>&1; then
@@ -182,8 +182,16 @@ check_for_updates() {
         
         if [ -n "$current_version" ] && [ -n "$latest_version" ] && [ "$current_version" != "$latest_version" ]; then
             echo -e "${YELLOW}📦 Update available: claude-fsd $current_version → $latest_version${NC}"
-            echo -e "${YELLOW}   Run: npm update -g claude-fsd${NC}"
-            echo
+            echo -e "${GREEN}🔄 Auto-updating claude-fsd...${NC}"
+            
+            # Attempt automatic update
+            if npm update -g claude-fsd >/dev/null 2>&1; then
+                echo -e "${GREEN}✅ Successfully updated to claude-fsd $latest_version${NC}"
+                echo
+            else
+                echo -e "${YELLOW}⚠️  Auto-update failed. Please run manually: npm update -g claude-fsd${NC}"
+                echo
+            fi
         fi
     fi
 }

package/bin/claudefsd-create-plan

@@ -57,10 +57,12 @@ The CLAUDE-NOTES.md should contain:
 - Areas that may need future clarification
 
 The PLAN.md should contain:
-- Ordered list of development tasks with [ ] checkboxes
-- Each task should be specific and actionable
+- Master plan limited to 100 lines maximum
+- High-level sections with [ ] checkboxes for completion tracking
+- For complex projects, reference detailed sub-plans in separate files (docs/plan-section1.md, docs/plan-section2.md, etc.)
 - Include proportional infrastructure setup (basic linting + pre-commit hooks)
 - Group related tasks into logical phases
+- If the plan would exceed 100 lines, create a master plan with section references and detailed sub-plans
 
 INFRASTRUCTURE PROPORTIONALITY RULES:
 - Basic linter + pre-commit hooks: Always include for any project
@@ -112,8 +114,10 @@ Using your deep strategic reasoning, create a comprehensive project architecture
    - Long-term maintainability strategy
 
 2. IMPLEMENTATION PLAN (docs/PLAN.md):
+   - Master plan limited to 100 lines maximum with high-level sections
+   - For complex projects, create detailed sub-plans in separate files (docs/plan-section1.md, etc.)
    - Phased development approach with clear milestones
-   - Detailed task breakdown with dependencies
+   - Task breakdown with dependencies (detailed in sub-plans if needed)
    - Risk assessment for each phase
    - Testing strategy integrated into each phase
    - Infrastructure needs (proportional to project size)

package/bin/claudefsd-dev

@@ -1,63 +1,69 @@
 #!/bin/bash
 #
-# Main development dispatcher - routes to appropriate development mode
-# Usage: claudefsd-dev [direct|iterative]
+# Main development dispatcher - now uses unified development mode by default
+# Usage: claudefsd-dev [direct|iterative|legacy-direct|legacy-iterative]
 # 
 # Modes:
-# direct: Single-context parallel execution (small to medium projects)
-# iterative: Multi-iteration loop development (large projects)
+# (default): Unified mode combining best of both approaches
+# direct: Legacy single-context parallel execution (deprecated)
+# iterative: Legacy multi-iteration loop development (deprecated)
+# legacy-direct: Force legacy direct execution mode
+# legacy-iterative: Force legacy iterative loop mode
 #
 # Examples:
-#   claudefsd-dev          # Auto-detect mode from project brief
-#   claudefsd-dev direct   # Force direct execution mode
-#   claudefsd-dev iterative # Force iterative loop mode
+#   claudefsd-dev                    # Use unified development mode (recommended)
+#   claudefsd-dev legacy-direct      # Force legacy direct execution mode
+#   claudefsd-dev legacy-iterative   # Force legacy iterative loop mode
 
 set -e
 
-# Parse command line arguments or auto-detect mode
+# Parse command line arguments
 DEV_MODE="$1"
+
+# Default to unified mode
 if [ -z "$DEV_MODE" ]; then
-    # Auto-detect mode from BRIEF.md
-    if [ -f "BRIEF.md" ] || [ -f "docs/BRIEF.md" ]; then
-        BRIEF_FILE="BRIEF.md"
-        [ -f "docs/BRIEF.md" ] && BRIEF_FILE="docs/BRIEF.md"
-        
-        # Look for indicators of small/medium vs large projects
-        if grep -qi "simple\|small\|quick\|prototype\|poc\|minimal\|script\|tool\|utility\|feature\|module" "$BRIEF_FILE"; then
-            DEV_MODE="direct"
-        else
-            DEV_MODE="iterative"
-        fi
-    else
-        DEV_MODE="iterative"  # Default to iterative for safety
-    fi
+    DEV_MODE="unified"
 fi
 
 echo "Development mode: $DEV_MODE"
 
 # Route to appropriate development script
 case "$DEV_MODE" in
+    unified)
+        echo "Launching unified development mode (recommended)..."
+        exec "$(dirname "$0")/claudefsd-dev-unified"
+        ;;
     direct)
-        echo "Launching direct execution mode..."
+        echo "WARNING: Legacy direct mode is deprecated. Consider using unified mode."
+        echo "Launching legacy direct execution mode..."
         exec "$(dirname "$0")/claudefsd-dev-direct"
         ;;
     iterative)
-        echo "Launching iterative development mode..."
+        echo "WARNING: Legacy iterative mode is deprecated. Consider using unified mode."
+        echo "Launching legacy iterative development mode..."
         exec "$(dirname "$0")/claudefsd-dev-iterative"
         ;;
-    small)
-        # Legacy support - map to direct
-        echo "Legacy 'small' mode - redirecting to direct execution..."
+    legacy-direct)
+        echo "Launching legacy direct execution mode..."
         exec "$(dirname "$0")/claudefsd-dev-direct"
         ;;
-    large)
-        # Legacy support - map to iterative
-        echo "Legacy 'large' mode - redirecting to iterative development..."
+    legacy-iterative)
+        echo "Launching legacy iterative development mode..."
         exec "$(dirname "$0")/claudefsd-dev-iterative"
         ;;
+    small)
+        # Legacy support - map to unified (was direct)
+        echo "Legacy 'small' mode - redirecting to unified development..."
+        exec "$(dirname "$0")/claudefsd-dev-unified"
+        ;;
+    large)
+        # Legacy support - map to unified (was iterative)
+        echo "Legacy 'large' mode - redirecting to unified development..."
+        exec "$(dirname "$0")/claudefsd-dev-unified"
+        ;;
     *)
         echo "Unknown development mode: $DEV_MODE"
-        echo "Valid modes: direct, iterative"
+        echo "Valid modes: unified (default), direct, iterative, legacy-direct, legacy-iterative"
         exit 1
         ;;
 esac

package/bin/claudefsd-dev-direct

@@ -66,7 +66,8 @@ echo
 # Go back to the project directory
 cd "$OLDPWD"
 
-# Build the omnibus prompt
+# Build the omnibus prompt  
+set +e  # Temporarily disable exit on error for prompt construction
 omnibus_prompt="You are an elite development team leader using Claude's Task agent capabilities for rapid parallel execution.
 
 **ANTI-GOLDPLATING DIRECTIVE**: This is direct execution mode optimized for small to medium projects. Focus on minimal viable solutions that meet requirements. Avoid over-engineering, unnecessary abstractions, or enterprise patterns unless explicitly required.
@@ -131,6 +132,8 @@ Then launch the Task agents to build this project rapidly and efficiently.
 
 Remember: This is a one-shot execution. Make it count!"
 
+set -e  # Re-enable exit on error
+
 echo "Running Claude dev-mini omnibus prompt..."
 echo "This will launch multiple parallel Task agents to complete the project..."
 echo

package/bin/claudefsd-dev-unified

@@ -0,0 +1,230 @@
+#!/bin/bash
+#
+# Unified development mode - combines best of direct and iterative approaches
+# Usage: claudefsd-dev-unified
+#
+# Features:
+# - Fail-fast loop detection and "all done" prompt from iterative mode
+# - Direct parallel Task agent execution from direct mode
+# - Intelligent task planning and coordination
+#
+
+set -e
+
+# Get the actual location of this script (resolving symlinks)
+if command -v realpath >/dev/null 2>&1; then
+    SCRIPT_PATH="$(realpath "$0")"
+elif command -v readlink >/dev/null 2>&1; then
+    # macOS doesn't have realpath by default, but has readlink
+    SCRIPT_PATH="$0"
+    while [ -L "$SCRIPT_PATH" ]; do
+        SCRIPT_PATH="$(readlink "$SCRIPT_PATH")"
+    done
+    SCRIPT_PATH="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)/$(basename "$SCRIPT_PATH")"
+else
+    # Fallback if neither command is available
+    SCRIPT_PATH="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
+fi
+
+# Get the directory containing the script
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+
+# Check dependencies
+"$SCRIPT_DIR/claudefsd-check-dependencies"
+
+# Function to check for required files
+check_requirements() {
+    # Load find_brief_file function
+    source "$SCRIPT_DIR/claudefsd-find-brief"
+    brief_file=$(find_brief_file 2>/dev/null || echo "")
+    
+    if [ -z "$brief_file" ]; then
+        echo "No BRIEF.md file found in docs/ or root directory. Please create one first."
+        exit 1
+    fi
+    
+    if [ ! -f "docs/PLAN.md" ]; then
+        echo "No docs/PLAN.md file found. Please run 'claudefsd create-plan' first."
+        exit 1
+    fi
+}
+
+# Check requirements
+check_requirements
+
+# Add counter for loop iterations
+LOOP_COUNTER=0
+
+# Failure detection variables
+CONSECUTIVE_FAST_ITERATIONS=0
+MIN_ITERATION_TIME=300  # 5 minutes in seconds
+
+while true; do
+    # Record iteration start time
+    ITERATION_START_TIME=$(date +%s)
+    
+    # Increment loop counter
+    LOOP_COUNTER=$((LOOP_COUNTER + 1))
+    
+    mkdir -p logs
+    # Use a temporary directory for tmp files
+    mkdir -p tmp
+    export TMPDIR=tmp/
+    LOGFILE="logs/claude-unified-$(date +%Y%m%d_%H%M%S).txt"
+
+    echo "Logging to ${LOGFILE} ..."
+
+    echo -e "\033[32m==================================================================\033[0m"
+    echo -e "\033[32m== UNIFIED DEVELOPMENT MODE - ITERATION $LOOP_COUNTER\033[0m"
+    echo -e "\033[32m==================================================================\033[0m"
+
+    # Check if this is the 4th iteration for megathinking mode
+    if [ $((LOOP_COUNTER % 4)) -eq 0 ]; then
+        echo -e "\033[33m**** MEGATHINKING MODE ACTIVATED ****\033[0m"
+        echo -e "\033[33mThis is your 4th development cycle. Taking a step back for architectural planning.\033[0m"
+        MEGATHINKING_MODE="**** MEGATHINKING MODE ACTIVATED ****\nThis is your 4th development cycle. Before proceeding with the next task, please take a step back and use megathinking mode to architecturally plan the next phase of development. Consider the overall structure of the codebase, potential refactoring opportunities, design patterns, technical debt, and how the current work connects to broader project goals.\n\n"
+        CLAUDE_MODEL="opus"
+    else
+        MEGATHINKING_MODE=""
+        CLAUDE_MODEL="sonnet"
+    fi
+
+    # Build the unified development prompt combining best of both modes
+    UNIFIED_PROMPT="$MEGATHINKING_MODE
+You are an elite development team leader working in an automated development environment. You combine intelligent task selection with parallel execution capabilities for maximum efficiency.
+
+**PROJECT CONTEXT:**
+$(source "$SCRIPT_DIR/claudefsd-find-brief" && brief_file=$(find_brief_file 2>/dev/null) && [ -n "$brief_file" ] && echo "=== PROJECT BRIEF ===" && cat "$brief_file" && echo "")
+$([ -f "docs/PLAN.md" ] && echo "=== DEVELOPMENT PLAN ===" && cat "docs/PLAN.md" && echo "")
+$([ -f "docs/REQUIREMENTS.md" ] && echo "=== REQUIREMENTS ===" && cat "docs/REQUIREMENTS.md" && echo "")
+$([ -f "docs/QUESTIONS.md" ] && echo "=== QUESTIONS ===" && cat "docs/QUESTIONS.md" && echo "")
+$([ -f "docs/CLAUDE-NOTES.md" ] && echo "=== TECHNICAL NOTES ===" && cat "docs/CLAUDE-NOTES.md" && echo "")
+$([ -f "README.md" ] && echo "=== README ===" && cat "README.md" && echo "")
+
+**IMPORTANT:** Before starting ANY work, you MUST read and understand:
+1. The project's CLAUDE.md file (if it exists) - this contains project-specific instructions
+2. The user's global CLAUDE.md file at ~/.claude/CLAUDE.md (if it exists) - this contains general development principles
+3. Ensure all your work follows the architectural and development guidelines from both files
+
+**CRITICAL ANTI-PATTERNS TO AVOID (from CLAUDE.md):**
+- NO CHEATING: Never disable tests, exclude files from compilation, or use silent fallbacks
+- FAIL FAST: Integration failures should throw exceptions, not return mock data
+- NO PRODUCTION FALLBACKS: Avoid try/catch blocks that hide errors with default values
+- NO BACKUP COPIES: Use git for version control, never create backup files
+- DELETE OLD CODE: Remove unused functions and scripts, keep the codebase clean
+
+**YOUR MISSION:**
+
+**PHASE 1: INTELLIGENT TASK ANALYSIS**
+1. Read the current docs/PLAN.md and identify all open tasks that need completion
+2. Analyze task dependencies and determine what can be done in parallel
+3. Consider the architectural implications of each task
+4. Prioritize tasks based on:
+   - Order in the plan (primary factor)
+   - Dependencies between tasks
+   - Risk and efficiency considerations
+   - Overall project architecture
+
+**PHASE 2: EXECUTION STRATEGY**
+Choose the optimal approach:
+
+**Option A: Single Focus Task** (for sequential dependencies or complex architectural work)
+- Select the highest priority open task
+- Implement with deep thinking and careful consideration
+- Update docs/PLAN.md to mark task as complete
+
+**Option B: Parallel Task Execution** (for independent tasks)
+- Identify 2-4 related but independent tasks that can be done simultaneously
+- Launch multiple Task agents with coordinated objectives
+- Each agent should understand the full project context
+- Ensure consistency across all parallel work
+
+**PHASE 3: COMPLETION CHECK**
+After completing work:
+1. Update docs/PLAN.md to reflect completed tasks
+2. Run any linters or tests specified in the project
+3. If ALL tasks in docs/PLAN.md are complete, respond with: **<ALL DONE>**
+
+**EXECUTION GUIDELINES:**
+- **BUILD BULLETPROOF**: Create robust solutions that handle edge cases
+- **STAY FOCUSED**: Only implement what's specified in docs/PLAN.md
+- **QUALITY FIRST**: Proper error handling, testing, and documentation
+- **ARCHITECTURAL THINKING**: Consider long-term maintainability
+
+**TASK AGENT COORDINATION:**
+When using parallel Task agents, ensure each one:
+- Has full project context and understands the architecture
+- Knows about related components they might need to integrate with
+- Follows all CLAUDE.md guidelines
+- Implements consistent code style and patterns
+- Handles proper error checking and edge cases
+
+**OUTPUT FORMAT:**
+1. **<task_analysis>**: List identified open tasks and selected approach
+2. **<execution>**: Details of your implementation work
+3. **<plan_updates>**: How you updated docs/PLAN.md to reflect progress
+4. **<completion_check>**: Status of remaining work, or **<ALL DONE>** if complete
+
+Begin by analyzing the current state of docs/PLAN.md and determining your execution strategy."
+
+    # Save the prompt to the log file first
+    echo "=== UNIFIED DEVELOPMENT PROMPT ===" > $LOGFILE
+    echo "$UNIFIED_PROMPT" >> $LOGFILE
+    echo "=== END PROMPT ===" >> $LOGFILE
+    echo "" >> $LOGFILE
+    echo "=== OUTPUT ===" >> $LOGFILE
+
+    # Run claude and append output to the log file
+    echo "Running unified development with $CLAUDE_MODEL model..."
+    time claude --model $CLAUDE_MODEL --dangerously-skip-permissions -p "$UNIFIED_PROMPT" 2>&1 | tee -a $LOGFILE
+
+    # Check if all tasks are complete
+    set +e
+    if grep -q "<ALL DONE>" $LOGFILE; then
+        echo -e "\033[32m==================================================================\033[0m"
+        echo -e "\033[32m== PROJECT COMPLETE - ALL TASKS FINISHED!\033[0m"
+        echo -e "\033[32m==================================================================\033[0m"
+        exit 0
+    fi
+    set -e
+
+    # Calculate iteration duration and check for failure patterns
+    ITERATION_END_TIME=$(date +%s)
+    ITERATION_DURATION=$((ITERATION_END_TIME - ITERATION_START_TIME))
+    
+    echo -e "\033[36mIteration $LOOP_COUNTER completed in ${ITERATION_DURATION}s\033[0m"
+    
+    # Check if iteration was suspiciously fast (likely failure mode)
+    if [ $ITERATION_DURATION -lt $MIN_ITERATION_TIME ]; then
+        CONSECUTIVE_FAST_ITERATIONS=$((CONSECUTIVE_FAST_ITERATIONS + 1))
+        echo -e "\033[33mWarning: Fast iteration detected (${ITERATION_DURATION}s < ${MIN_ITERATION_TIME}s threshold)\033[0m"
+        echo -e "\033[33mConsecutive fast iterations: $CONSECUTIVE_FAST_ITERATIONS/3\033[0m"
+        
+        # Exit if too many consecutive fast iterations (likely Claude API failure)
+        if [ $CONSECUTIVE_FAST_ITERATIONS -ge 3 ]; then
+            echo -e "\033[31m==================================================================\033[0m"
+            echo -e "\033[31m== FAILURE MODE DETECTED - THROTTLING ACTIVATED\033[0m"
+            echo -e "\033[31m==================================================================\033[0m"
+            echo -e "\033[31mDetected 3 consecutive iterations under ${MIN_ITERATION_TIME}s each.\033[0m"
+            echo -e "\033[31mThis usually indicates Claude API issues (token limits, etc).\033[0m"
+            echo -e "\033[31m\033[0m"
+            echo -e "\033[31mSuggested actions:\033[0m"
+            echo -e "\033[31m- Check your Claude API token limits\033[0m"
+            echo -e "\033[31m- Wait a few minutes and restart with: claudefsd dev\033[0m"
+            echo -e "\033[31m- Review logs in: logs/\033[0m"
+            echo -e "\033[31m==================================================================\033[0m"
+            exit 1
+        fi
+        
+        # Add exponential backoff delay for fast iterations
+        BACKOFF_DELAY=$((CONSECUTIVE_FAST_ITERATIONS * 60))  # 1min, 2min, 3min
+        echo -e "\033[33mApplying backoff delay: ${BACKOFF_DELAY}s\033[0m"
+        sleep $BACKOFF_DELAY
+    else
+        # Reset counter on successful iteration
+        CONSECUTIVE_FAST_ITERATIONS=0
+        echo -e "\033[32mNormal iteration timing - continuing...\033[0m"
+    fi
+
+    sleep 1
+done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-fsd",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "description": "Claude Full Self Drive tools for autonomous AI-powered development",
   "bin": {
     "claude-fsd": "bin/claude-fsd",