claude-fsd 1.5.26 → 1.5.28

package/README.md

@@ -83,8 +83,14 @@ Runs the development agent fleet. This command:
 - Updates the plan to track progress
 - Repeats until all tasks are done
 
+Options:
+- `--max-time=MINUTES` - Maximum total runtime (default: 120 minutes)
+- `--working-dir=DIR` - Directory containing BRIEF.md and PLAN.md (default: docs)
+
 Every 4th cycle, it activates "megathinking mode" using ultrathink for deep architectural planning.
 
+**@STOP Checkpoint**: Add `@STOP` on its own line in PLAN.md to pause when all preceding tasks complete. Useful for human review or deployment gates.
+
 #### claudefsd-interview
 Interactive expert Q&A session that:
 - Analyzes your BRIEF.md with multiple AI personas (DBA, Architect, UX Expert, etc.)
@@ -137,12 +143,13 @@ This isn't sci-fi level "sleep through the entire project" automation - it's mor
 - Unix-like environment (macOS, Linux)
 - [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command)
 
-### Optional (but recommended)
-- [Codex](https://github.com/Codex-ai/codex) - For enhanced code review capabilities
-- OpenAI API key - For Codex features (set `OPENAI_API_KEY` environment variable)
-
 ## Project Structure
 
+**Flexible Structure:** Files can be placed in either `docs/` (default) or root directory `.`
+- System automatically detects file locations
+- Use `docs/` for larger projects to keep files organized
+- Use root `.` for smaller projects for simplicity
+
 Default structure (using 'docs' as working directory):
 ```
 your-project/
@@ -158,6 +165,16 @@ your-project/
 └── [your code files]
 ```
 
+Simple structure (files in root):
+```
+your-project/
+├── BRIEF.md
+├── PLAN.md
+├── CLAUDE-NOTES.md
+├── logs/
+└── [your code files]
+```
+
 With custom working directory:
 ```
 your-project/

package/bin/claudefsd

@@ -42,11 +42,18 @@ get_default_choice() {
     source "$(dirname "$0")/claudefsd-find-brief"
     if ! find_brief_file >/dev/null 2>&1; then
         echo "0"
-    elif [ ! -f "$WORKING_DIR/REQUIREMENTS.md" ] && [ ! -f "$WORKING_DIR/QUESTIONS.md" ]; then
+    fi
+
+    # Use flexible file detection
+    local requirements_file=$(find_project_file "REQUIREMENTS.md" 2>/dev/null || echo "")
+    local questions_file=$(find_project_file "QUESTIONS.md" 2>/dev/null || echo "")
+    local plan_file=$(find_project_file "PLAN.md" 2>/dev/null || echo "")
+
+    if [ -z "$requirements_file" ] && [ -z "$questions_file" ]; then
         echo "1"  # Interactive interview
-    elif [ -f "$WORKING_DIR/REQUIREMENTS.md" ] && [ ! -f "$WORKING_DIR/PLAN.md" ]; then
+    elif [ -n "$requirements_file" ] && [ -z "$plan_file" ]; then
         echo "2"  # Create plan from requirements
-    elif [ -f "$WORKING_DIR/QUESTIONS.md" ] && [ ! -f "$WORKING_DIR/PLAN.md" ]; then
+    elif [ -n "$questions_file" ] && [ -z "$plan_file" ]; then
         echo "2"  # Create plan from questions
     else
         echo "3"  # Development mode
@@ -83,10 +90,14 @@ show_menu() {
         echo "  1) Interview - Gather requirements through expert Q&A"
     fi
     
-    # Show create plan option based on what exists
-    if [ -f "$WORKING_DIR/REQUIREMENTS.md" ]; then
+    # Show create plan option based on what exists (use flexible detection)
+    source "$(dirname "$0")/claudefsd-find-brief"
+    local requirements_file=$(find_project_file "REQUIREMENTS.md" 2>/dev/null || echo "")
+    local questions_file=$(find_project_file "QUESTIONS.md" 2>/dev/null || echo "")
+
+    if [ -n "$requirements_file" ]; then
         echo "  2) Create plan - Generate development plan from requirements"
-    elif [ -f "$WORKING_DIR/QUESTIONS.md" ]; then
+    elif [ -n "$questions_file" ]; then
         echo "  2) Create plan - Generate plan from answered questions"
     else
         echo "  2) [Requires interview first]"
@@ -113,9 +124,14 @@ show_menu() {
         echo "  📝 Interview session: $session_status ($total_questions questions)"
     fi
     
-    [ -f "$WORKING_DIR/REQUIREMENTS.md" ] && echo "  ✓ $WORKING_DIR/REQUIREMENTS.md exists" || echo "  ✗ $WORKING_DIR/REQUIREMENTS.md missing"
-    [ -f "$WORKING_DIR/QUESTIONS.md" ] && echo "  ✓ $WORKING_DIR/QUESTIONS.md exists" || echo "  ✗ $WORKING_DIR/QUESTIONS.md missing"
-    [ -f "$WORKING_DIR/PLAN.md" ] && echo "  ✓ $WORKING_DIR/PLAN.md exists" || echo "  ✗ $WORKING_DIR/PLAN.md missing"
+    # Show status with flexible file detection
+    local requirements_file=$(find_project_file "REQUIREMENTS.md" 2>/dev/null || echo "")
+    local questions_file=$(find_project_file "QUESTIONS.md" 2>/dev/null || echo "")
+    local plan_file=$(find_project_file "PLAN.md" 2>/dev/null || echo "")
+
+    [ -n "$requirements_file" ] && echo "  ✓ $requirements_file exists" || echo "  ✗ REQUIREMENTS.md missing"
+    [ -n "$questions_file" ] && echo "  ✓ $questions_file exists" || echo "  ✗ QUESTIONS.md missing"
+    [ -n "$plan_file" ] && echo "  ✓ $plan_file exists" || echo "  ✗ PLAN.md missing"
     echo
 }
 
@@ -262,8 +278,12 @@ if [ $# -eq 0 ]; then
             exec "$(dirname "$0")/claudefsd-interview" --working-dir="$WORKING_DIR"
             ;;
         2)
-            # Create plan - check what source to use
-            if [ -f "$WORKING_DIR/REQUIREMENTS.md" ] || [ -f "$WORKING_DIR/QUESTIONS.md" ]; then
+            # Create plan - check what source to use (flexible detection)
+            source "$(dirname "$0")/claudefsd-find-brief"
+            requirements_file=$(find_project_file "REQUIREMENTS.md" 2>/dev/null || echo "")
+            questions_file=$(find_project_file "QUESTIONS.md" 2>/dev/null || echo "")
+
+            if [ -n "$requirements_file" ] || [ -n "$questions_file" ]; then
                 echo -e "${GREEN}Creating plan from project inputs...${NC}"
                 echo
                 exec "$(dirname "$0")/claudefsd-create-plan" --working-dir="$WORKING_DIR"

package/bin/claudefsd-analyze-brief

@@ -16,7 +16,7 @@ exec "$(dirname "$0")/claudefsd-analyze-brief-personas" "$@"
 
 mkdir -p logs
 
-# Use a temporary directory for tmp files, as codex is sandboxed to this directory
+# Use a temporary directory for tmp files
 mkdir -p tmp
 export TMPDIR=tmp/
 
@@ -67,17 +67,8 @@ DO NOT answer the questions yourself - just generate them for the user to answer
 "
 
 # run BA's
-echo "Running claude with sonnet model with ultrathink..."
-claude --model sonnet --dangerously-skip-permissions -p "$prompt1" | tee >(cat > $LOGFILE-ba1)
-
-# Only run codex if available
-if command -v codex >/dev/null 2>&1; then
-    echo "Running codex o3 (results won't display)..."
-    codex -m o3 --full-auto -q "$prompt1" > $LOGFILE-ba2
-else
-    echo "Warning: codex not found, skipping enhanced analysis"
-    echo "Codex not available, skipping o3 analysis" > $LOGFILE-ba2
-fi
+echo "Running claude with opus model with ultrathink..."
+claude --model opus --dangerously-skip-permissions -p "$prompt1" | tee >(cat > $LOGFILE-ba1)
 
 echo -e "\033[32m==================================================================\033[0m"
 echo -e "\033[32m== ANALYSIS COMPLETE\033[0m"

package/bin/claudefsd-analyze-brief-personas

@@ -83,7 +83,7 @@ Include only personas that are truly relevant to this project.
 "
 
 echo "Determining relevant expert personas..."
-PERSONAS=$(claude --model sonnet -p "$coordinator_prompt" 2>/dev/null | tail -1)
+PERSONAS=$(claude --model opus -p "$coordinator_prompt" 2>/dev/null | tail -1)
 
 # Clean up and validate personas
 PERSONAS=$(echo "$PERSONAS" | tr -d ' \n\r')
@@ -172,7 +172,7 @@ Output ONLY the questions, one per line, no numbering or bullets.
 "
     
     # Generate questions
-    QUESTIONS=$(claude --model sonnet -p "$batch_prompt" 2>/dev/null)
+    QUESTIONS=$(claude --model opus -p "$batch_prompt" 2>/dev/null)
     
     # Add section header
     echo "" >> "$WORKING_DIR/QUESTIONS.md"

package/bin/claudefsd-create-plan

@@ -19,7 +19,7 @@ $(dirname "$0")/claudefsd-check-dependencies
 
 mkdir -p logs
 
-# Use a temporary directory for tmp files, as codex is sandboxed to this directory
+# Use a temporary directory for tmp files
 mkdir -p tmp
 export TMPDIR=tmp/
 
@@ -31,8 +31,12 @@ if [ $? -ne 0 ]; then
     exit 1
 fi
 
-if [ ! -f "$WORKING_DIR/QUESTIONS.md" ] && [ ! -f "$WORKING_DIR/REQUIREMENTS.md" ]; then
-    echo "No $WORKING_DIR/QUESTIONS.md or $WORKING_DIR/REQUIREMENTS.md found."
+# Check for required input files using flexible detection
+questions_file=$(find_project_file "QUESTIONS.md" 2>/dev/null || echo "")
+requirements_file=$(find_project_file "REQUIREMENTS.md" 2>/dev/null || echo "")
+
+if [ -z "$questions_file" ] && [ -z "$requirements_file" ]; then
+    echo "No QUESTIONS.md or REQUIREMENTS.md found in $WORKING_DIR/ or root directory."
     echo "Please run either:"
     echo "  - 'claudefsd analyze-brief' to generate questions, or"
     echo "  - 'claudefsd interview' to conduct an interactive interview"
@@ -45,22 +49,48 @@ echo -e "\033[32m===============================================================
 echo -e "\033[32m== CREATING PLAN FROM PROJECT INPUTS\033[0m"
 echo -e "\033[32m==================================================================\033[0m"
 
+# Build list of files to read (using flexible paths)
+plan_file=$(find_project_file "PLAN.md" 2>/dev/null || echo "")
+notes_file=$(find_project_file "CLAUDE-NOTES.md" 2>/dev/null || echo "")
+ideas_file=$(find_project_file "IDEAS.md" 2>/dev/null || echo "")
+webtests_file=$(find_project_file "WEBTESTS.md" 2>/dev/null || echo "")
+readme_file=$(find_project_file "README.md" 2>/dev/null || echo "")
+
+# Build file list for prompt
+file_list="- $BRIEF_FILE -- the project brief"
+[ -n "$questions_file" ] && file_list="$file_list
+- $questions_file -- the project questions (with answers) from analyze-brief or interview"
+[ -n "$requirements_file" ] && file_list="$file_list
+- $requirements_file -- consolidated requirements from interview process"
+[ -n "$notes_file" ] && file_list="$file_list
+- $notes_file -- AI's working notes and understanding"
+[ -n "$plan_file" ] && file_list="$file_list
+- $plan_file -- the project plan"
+[ -n "$ideas_file" ] && file_list="$file_list
+- $ideas_file -- the backlog of future ideas"
+[ -n "$webtests_file" ] && file_list="$file_list
+- $webtests_file -- the project web tests"
+[ -n "$readme_file" ] && file_list="$file_list
+- $readme_file -- the project README"
+
+# Determine output paths (prefer working dir if it exists, otherwise root)
+if [ -d "$WORKING_DIR" ] && [ "$WORKING_DIR" != "." ]; then
+    output_notes="$WORKING_DIR/CLAUDE-NOTES.md"
+    output_plan="$WORKING_DIR/PLAN.md"
+else
+    output_notes="CLAUDE-NOTES.md"
+    output_plan="PLAN.md"
+fi
+
     prompt2="
 Read and analyze these project files if they exist:
-- $BRIEF_FILE -- the project brief
-- $WORKING_DIR/QUESTIONS.md -- the project questions (with answers) from analyze-brief or interview
-- $WORKING_DIR/REQUIREMENTS.md -- consolidated requirements from interview process
-- $WORKING_DIR/CLAUDE-NOTES.md -- AI's working notes and understanding
-- $WORKING_DIR/PLAN.md -- the project plan
-- $WORKING_DIR/IDEAS.md -- the backlog of future ideas
-- $WORKING_DIR/WEBTESTS.md -- the project web tests
-- $WORKING_DIR/README.md -- the project README (if exists in working directory)
+$file_list
 
 Your job, as a megathinking architect and project manager, is to create the project plan and working notes.
 
-1. Read through the BRIEF.md and any available requirements/questions ($WORKING_DIR/QUESTIONS.md and/or $WORKING_DIR/REQUIREMENTS.md).
-2. Update or create $WORKING_DIR/CLAUDE-NOTES.md with your interpretation and understanding of the project.
-3. Update or create $WORKING_DIR/PLAN.md with a detailed implementation plan based on all available inputs.
+1. Read through the BRIEF.md and any available requirements/questions.
+2. Update or create $output_notes with your interpretation and understanding of the project.
+3. Update or create $output_plan with a detailed implementation plan based on all available inputs.
 
 The CLAUDE-NOTES.md should contain:
 - Your understanding of the project goals and requirements
@@ -71,7 +101,7 @@ The CLAUDE-NOTES.md should contain:
 The PLAN.md should contain:
 - 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 ($WORKING_DIR/plan-section1.md, $WORKING_DIR/plan-section2.md, etc.)
+- For complex projects, reference detailed sub-plans in separate files (plan-section1.md, 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
@@ -102,15 +132,15 @@ Take your time to think deeply about the best solution before generating your pl
 # Prepend ultrathink to the prompt
 prompt2="$ultrathink_instruction$prompt2"
 
-# Run planning with sonnet + ultrathink
-echo "Running claude with sonnet model (ultrathink mode)..."
-claude --model sonnet --dangerously-skip-permissions -p "$prompt2" | tee >(cat > $LOGFILE-ba3)
+# Run planning with opus + ultrathink
+echo "Running claude with opus model (ultrathink mode)..."
+claude --model opus --dangerously-skip-permissions -p "$prompt2" | tee >(cat > $LOGFILE-ba3)
 
 echo -e "\033[32m==================================================================\033[0m"
 echo -e "\033[32m== PLAN CREATION COMPLETE\033[0m"
 echo -e "\033[32m==================================================================\033[0m"
-echo "Plan created in $WORKING_DIR/PLAN.md"
-echo "Working notes saved in $WORKING_DIR/CLAUDE-NOTES.md"
+echo "Plan created in $output_plan"
+echo "Working notes saved in $output_notes"
 echo "You can now run 'claudefsd dev' to start the development process."
 
 

package/bin/claudefsd-dev

@@ -1,28 +1,43 @@
 #!/bin/bash
 #
 # Main development mode - intelligent task selection with parallel execution
-# Usage: claudefsd-dev
+# Usage: claudefsd-dev [--working-dir=DIR] [--max-time=MINUTES]
+#
+# Options:
+#   --working-dir=DIR    Directory containing BRIEF.md and PLAN.md (default: docs)
+#   --max-time=MINUTES   Maximum total runtime in minutes (default: 120)
 #
 # 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
+# - @STOP marker support: stops when all tasks before @STOP are complete
+# - Max runtime limit to prevent runaway sessions
 #
 
 #set -e
 
-# Parse --working-dir parameter
+# Parse command line parameters
 WORKING_DIR="docs"
+MAX_TIME_MINUTES=120
 for arg in "$@"; do
     case $arg in
         --working-dir=*)
             WORKING_DIR="${arg#*=}"
             shift
             ;;
+        --max-time=*)
+            MAX_TIME_MINUTES="${arg#*=}"
+            shift
+            ;;
     esac
 done
 export CLAUDEFSD_WORKING_DIR="$WORKING_DIR"
 
+# Convert max time to seconds and record start time
+MAX_TIME_SECONDS=$((MAX_TIME_MINUTES * 60))
+OVERALL_START_TIME=$(date +%s)
+
 # Get the actual location of this script (resolving symlinks)
 if command -v realpath >/dev/null 2>&1; then
     SCRIPT_PATH="$(realpath "$0")"
@@ -46,17 +61,18 @@ SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
 
 # Function to check for required files
 check_requirements() {
-    # Load find_brief_file function
+    # Load file finding functions
     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 $WORKING_DIR/ or root directory. Please create one first."
         exit 1
     fi
-    
-    if [ ! -f "$WORKING_DIR/PLAN.md" ]; then
-        echo "No $WORKING_DIR/PLAN.md file found. Please run 'claudefsd create-plan' first."
+
+    plan_file=$(find_project_file "PLAN.md" 2>/dev/null || echo "")
+    if [ -z "$plan_file" ]; then
+        echo "No PLAN.md file found in $WORKING_DIR/ or root directory. Please run 'claudefsd create-plan' first."
         exit 1
     fi
 }
@@ -107,10 +123,10 @@ Take your time to think deeply about the optimal approach before proceeding.
 </ultrathink>
 
 "
-        CLAUDE_MODEL="sonnet"
+        CLAUDE_MODEL="opus"
     else
         MEGATHINKING_MODE=""
-        CLAUDE_MODEL="sonnet"
+        CLAUDE_MODEL="opus"
     fi
 
     # Build the development prompt combining intelligent task selection with parallel execution
@@ -119,37 +135,43 @@ You are an elite AI developer working in an automated development environment. Y
 
 **PROJECT FILES TO READ AND ANALYZE:**"
 
-    # Build file list more safely
+    # Build file list using flexible file detection
     source "$SCRIPT_DIR/claudefsd-find-brief"
+
     brief_file=$(find_brief_file 2>/dev/null || echo "")
     if [ -n "$brief_file" ]; then
         DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
 - $brief_file (project brief)"
     fi
-    
-    if [ -f "$WORKING_DIR/PLAN.md" ]; then
+
+    plan_file=$(find_project_file "PLAN.md" 2>/dev/null || echo "")
+    if [ -n "$plan_file" ]; then
         DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
-- $WORKING_DIR/PLAN.md (development plan with tasks)"
+- $plan_file (development plan with tasks)"
     fi
-    
-    if [ -f "$WORKING_DIR/REQUIREMENTS.md" ]; then
+
+    requirements_file=$(find_project_file "REQUIREMENTS.md" 2>/dev/null || echo "")
+    if [ -n "$requirements_file" ]; then
         DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
-- $WORKING_DIR/REQUIREMENTS.md (project requirements)"
+- $requirements_file (project requirements)"
     fi
-    
-    if [ -f "$WORKING_DIR/QUESTIONS.md" ]; then
+
+    questions_file=$(find_project_file "QUESTIONS.md" 2>/dev/null || echo "")
+    if [ -n "$questions_file" ]; then
         DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
-- $WORKING_DIR/QUESTIONS.md (interview Q&A)"
+- $questions_file (interview Q&A)"
     fi
-    
-    if [ -f "$WORKING_DIR/CLAUDE-NOTES.md" ]; then
+
+    notes_file=$(find_project_file "CLAUDE-NOTES.md" 2>/dev/null || echo "")
+    if [ -n "$notes_file" ]; then
         DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
-- $WORKING_DIR/CLAUDE-NOTES.md (technical notes)"
+- $notes_file (technical notes)"
     fi
-    
-    if [ -f "$WORKING_DIR/README.md" ]; then
+
+    readme_file=$(find_project_file "README.md" 2>/dev/null || echo "")
+    if [ -n "$readme_file" ]; then
         DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
-- $WORKING_DIR/README.md (project readme)"
+- $readme_file (project readme)"
     fi
     
     if [ -f "CLAUDE.md" ]; then
@@ -179,7 +201,7 @@ You are an elite AI developer working in an automated development environment. Y
 **YOUR MISSION:**
 
 **PHASE 1: TASK SELECTION**
-1. Read $WORKING_DIR/PLAN.md and work through tasks in order
+1. Read $plan_file and work through tasks in order
 2. If a phase references a sub-plan file, read that file as well
 3. Complete tasks in the order they appear - don't skip ahead
 4. Identify if tasks can be done in parallel
@@ -189,7 +211,7 @@ Choose the optimal approach:
 
 **Option A: Single Focus Task** (for sequential dependencies or complex architectural work)
 - Implement the next task in order using appropriate tools (Edit, Write, Bash, etc.)
-- Update $WORKING_DIR/PLAN.md to mark task as complete with [x]
+- Update $plan_file to mark task as complete with [x]
 
 **Option B: Parallel Task Execution** (for independent tasks)
 - Identify 2-4 related but independent tasks that can be done simultaneously
@@ -199,13 +221,13 @@ Choose the optimal approach:
 
 **PHASE 3: COMPLETION CHECK**
 After completing work:
-1. Update $WORKING_DIR/PLAN.md to reflect completed tasks
+1. Update $plan_file to reflect completed tasks
 2. Run any linters or tests specified in the project
 3. Report on what was accomplished and what remains
 
 **EXECUTION GUIDELINES:**
 - **BUILD BULLETPROOF**: Create robust solutions that handle edge cases
-- **STAY FOCUSED**: Only implement what's specified in $WORKING_DIR/PLAN.md
+- **STAY FOCUSED**: Only implement what's specified in $plan_file
 - **QUALITY FIRST**: Proper error handling, testing, and documentation
 - **ARCHITECTURAL THINKING**: Consider long-term maintainability
 
@@ -220,10 +242,10 @@ When using parallel Task agents, ensure each one:
 **OUTPUT FORMAT:**
 1. **<task_analysis>**: List identified open tasks and selected approach
 2. **<execution>**: Details of your ACTUAL implementation work (code written, files edited, commands run)
-3. **<plan_updates>**: How you updated $WORKING_DIR/PLAN.md to reflect progress
+3. **<plan_updates>**: How you updated $plan_file to reflect progress
 4. **<completion_check>**: Status of remaining work
 
-IMPORTANT: You must ACTUALLY IMPLEMENT tasks, not just describe what should be done. Use Edit, Write, Bash, and Task tools to complete real work. Begin by analyzing $WORKING_DIR/PLAN.md and then IMPLEMENT the next task in order."
+IMPORTANT: You must ACTUALLY IMPLEMENT tasks, not just describe what should be done. Use Edit, Write, Bash, and Task tools to complete real work. Begin by analyzing $plan_file and then IMPLEMENT the next task in order."
 
     # Save the prompt to the log file first
     echo "=== DEVELOPMENT PROMPT ===" > $LOGFILE
@@ -243,7 +265,7 @@ IMPORTANT: You must ACTUALLY IMPLEMENT tasks, not just describe what should be d
     echo -e "\033[32m== REVIEWING/VERIFYING WORK\033[0m"
     echo -e "\033[32m==================================================================\033[0m"
 
-    # Define the verifier prompt
+    # Define the verifier prompt (reuse plan_file from earlier)
     VERIFIER_PROMPT="You are an expert code reviewer tasked with verifying a developer's work.
 
 **DEVELOPER'S OUTPUT:**
@@ -254,13 +276,13 @@ $DEVELOPER_OUTPUT
 2. Verify the work was actually completed by checking files
 3. Look for any cheating patterns (disabled tests, silent fallbacks, etc.)
 4. Create a git commit (see guidelines below)
-5. Check if ALL tasks in $WORKING_DIR/PLAN.md are now complete
+5. Check if ALL tasks in $plan_file are now complete
 
 **VERIFICATION CHECKLIST:**
 - Did the developer actually implement code (not just analyze)?
 - Are all changes working correctly?
 - Do tests pass (if applicable)?
-- Is the task properly marked as complete in $WORKING_DIR/PLAN.md?
+- Is the task properly marked as complete in $plan_file?
 
 **GIT COMMIT GUIDELINES:**
 - If the code looks good: Definitely commit with a clear message
@@ -294,6 +316,38 @@ Be thorough but concise in your verification."
         exit 0
     fi
 
+    # Check for @STOP marker in plan file - if all tasks before @STOP are complete, pause for human review
+    if [ -n "$plan_file" ] && grep -q "@STOP" "$plan_file"; then
+        # Extract content before @STOP and check if any tasks are incomplete
+        BEFORE_STOP=$(sed -n '1,/@STOP/p' "$plan_file")
+        # Check for incomplete tasks ([ ] or - [ ]) before @STOP
+        if ! echo "$BEFORE_STOP" | grep -qE '\[ \]'; then
+            echo -e "\033[33m==================================================================\033[0m"
+            echo -e "\033[33m== @STOP CHECKPOINT REACHED\033[0m"
+            echo -e "\033[33m==================================================================\033[0m"
+            echo -e "\033[33mAll tasks before @STOP marker are complete.\033[0m"
+            echo -e "\033[33mPausing for human review/deployment/intervention.\033[0m"
+            echo -e "\033[33mTo continue: remove or move @STOP in $plan_file, then restart.\033[0m"
+            echo -e "\033[33m==================================================================\033[0m"
+            exit 0
+        fi
+    fi
+
+    # Check if max runtime has been exceeded
+    CURRENT_TIME=$(date +%s)
+    ELAPSED_SECONDS=$((CURRENT_TIME - OVERALL_START_TIME))
+    ELAPSED_MINUTES=$((ELAPSED_SECONDS / 60))
+    if [ $ELAPSED_SECONDS -ge $MAX_TIME_SECONDS ]; then
+        echo -e "\033[33m==================================================================\033[0m"
+        echo -e "\033[33m== MAX RUNTIME REACHED (${ELAPSED_MINUTES}m / ${MAX_TIME_MINUTES}m)\033[0m"
+        echo -e "\033[33m==================================================================\033[0m"
+        echo -e "\033[33mStopping after ${MAX_TIME_MINUTES} minutes as configured.\033[0m"
+        echo -e "\033[33mTo continue: restart with 'claudefsd dev' or increase --max-time\033[0m"
+        echo -e "\033[33m==================================================================\033[0m"
+        exit 0
+    fi
+    echo -e "\033[36mTotal runtime: ${ELAPSED_MINUTES}m / ${MAX_TIME_MINUTES}m\033[0m"
+
     # Calculate iteration duration and check for failure patterns
     ITERATION_END_TIME=$(date +%s)
     ITERATION_DURATION=$((ITERATION_END_TIME - ITERATION_START_TIME))

package/bin/claudefsd-find-brief

@@ -5,7 +5,7 @@
 find_brief_file() {
     # Use environment variable if set, otherwise default to "docs"
     local working_dir="${CLAUDEFSD_WORKING_DIR:-docs}"
-    
+
     if [ -f "$working_dir/BRIEF.md" ]; then
         echo "$working_dir/BRIEF.md"
     elif [ -f "BRIEF.md" ]; then
@@ -15,6 +15,22 @@ find_brief_file() {
     fi
 }
 
+# Generic function to find any file in working dir or root
+# Usage: find_project_file "PLAN.md"
+# Returns: path to file (prefers $WORKING_DIR/file, falls back to ./file)
+find_project_file() {
+    local filename="$1"
+    local working_dir="${CLAUDEFSD_WORKING_DIR:-docs}"
+
+    if [ -f "$working_dir/$filename" ]; then
+        echo "$working_dir/$filename"
+    elif [ -f "$filename" ]; then
+        echo "$filename"
+    else
+        return 1
+    fi
+}
+
 # If called directly, just output the path
 if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
     find_brief_file

package/bin/claudefsd-interview

@@ -193,7 +193,7 @@ prepare_next_question_bg() {
     coordinator_prompt="${coordinator_prompt//\{qa_summary_by_domain\}/$qa_summary}"
     
     # Get coordinator decision
-    local next_persona=$(claude --model sonnet -p "$coordinator_prompt" 2>/dev/null | tail -1)
+    local next_persona=$(claude --model opus -p "$coordinator_prompt" 2>/dev/null | tail -1)
     
     # Validate and clean decision - remove spaces, newlines, and markdown formatting
     next_persona=$(echo "$next_persona" | tr -d ' \n\r' | sed 's/[*_`]//g')
@@ -312,7 +312,7 @@ ${prompt_template}"
             prompt_template="${prompt_template//\{security_qa_history\}/$persona_qa}"
             
             # Get question from Claude
-            local question=$(claude --model sonnet -p "$prompt_template" 2>/dev/null | tail -1)
+            local question=$(claude --model opus -p "$prompt_template" 2>/dev/null | tail -1)
             echo "$question" > "$QUESTION_CACHE"
             
             # Question is ready in cache, no output needed
@@ -384,7 +384,7 @@ Create a comprehensive requirements document that:
 Format the output as a clean, well-structured markdown document suitable for feeding into project planning.
 "
     
-    claude --model sonnet -p "$consolidation_prompt" > "$REQUIREMENTS_FILE"
+    claude --model opus -p "$consolidation_prompt" > "$REQUIREMENTS_FILE"
     
     echo -e "${GREEN}Requirements consolidated in $REQUIREMENTS_FILE${NC}"
     

package/package.json

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