claude-fsd 1.5.27 → 1.5.29

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.)

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")"
@@ -168,13 +183,22 @@ You are an elite AI developer working in an automated development environment. Y
         DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
 - $HOME/.claude/CLAUDE.md (global development principles)"
     fi
-    
+
+    # Check for human feedback file
+    feedback_file=$(find_project_file "FEEDBACK.md" 2>/dev/null || echo "")
+    if [ -n "$feedback_file" ]; then
+        DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
+- $feedback_file (URGENT: Human feedback requiring immediate attention)"
+    fi
+
     DEVELOPMENT_PROMPT="$DEVELOPMENT_PROMPT
 
 **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 $HOME/.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
+2. The user's global CLAUDE.md file at \$HOME/.claude/CLAUDE.md (if it exists) - this contains general development principles
+3. If FEEDBACK.md exists, READ IT FIRST - it contains urgent human feedback that takes priority
+4. Read the '## Test Infrastructure' section in $plan_file for test commands
+5. 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
@@ -191,23 +215,30 @@ You are an elite AI developer working in an automated development environment. Y
 3. Complete tasks in the order they appear - don't skip ahead
 4. Identify if tasks can be done in parallel
 
-**PHASE 2: EXECUTION STRATEGY**
-Choose the optimal approach:
+**PHASE 2: EXECUTION STRATEGY (TDD REQUIRED)**
+You MUST follow Test-Driven Development:
+
+1. **RED**: Write a failing test first that defines the expected behavior
+2. **GREEN**: Write the minimum code to make the test pass
+3. **REFACTOR**: Clean up the code while keeping tests passing
+
+For each task:
+- Write the test BEFORE writing implementation code
+- Run tests using commands from '## Test Infrastructure' in $plan_file
+- Only mark task complete after tests pass
 
 **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 $plan_file to mark task as complete with [x]
+- Follow TDD cycle for the next task
+- Update $plan_file to mark task as complete with [x] ONLY after tests pass
 
 **Option B: Parallel Task Execution** (for independent tasks)
-- Identify 2-4 related but independent tasks that can be done simultaneously
-- Use the Task tool to launch multiple agents with specific implementation briefs
-- Each agent brief should include full project context and specific implementation goals
-- Coordinate the parallel work to ensure consistency
+- Each parallel agent must also follow TDD
+- Coordinate the parallel work to ensure test consistency
 
 **PHASE 3: COMPLETION CHECK**
 After completing work:
-1. Update $plan_file to reflect completed tasks
-2. Run any linters or tests specified in the project
+1. Run ALL tests to verify nothing is broken
+2. Update $plan_file to reflect completed tasks (only if tests pass)
 3. Report on what was accomplished and what remains
 
 **EXECUTION GUIDELINES:**
@@ -250,8 +281,9 @@ 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 (reuse plan_file from earlier)
-    VERIFIER_PROMPT="You are an expert code reviewer tasked with verifying a developer's work.
+    # Define the verifier prompt - CODE REVIEW ONLY, no test running
+    VERIFIER_PROMPT="You are an expert code reviewer. Your job is CODE REVIEW and GIT COMMITS only.
+DO NOT run tests - a separate Tester agent will handle that.
 
 **DEVELOPER'S OUTPUT:**
 $DEVELOPER_OUTPUT
@@ -259,14 +291,15 @@ $DEVELOPER_OUTPUT
 **YOUR TASKS:**
 1. Review what the developer claims to have done
 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 $plan_file are now complete
+3. Look for cheating patterns (disabled tests, silent fallbacks, mock data, etc.)
+4. Check code quality: proper error handling, no obvious bugs
+5. Create a git commit (see guidelines below)
 
-**VERIFICATION CHECKLIST:**
+**CODE REVIEW CHECKLIST:**
 - Did the developer actually implement code (not just analyze)?
-- Are all changes working correctly?
-- Do tests pass (if applicable)?
+- Did the developer follow TDD (wrote tests before implementation)?
+- Are there any cheating patterns or anti-patterns?
+- Is the code well-structured and maintainable?
 - Is the task properly marked as complete in $plan_file?
 
 **GIT COMMIT GUIDELINES:**
@@ -276,12 +309,12 @@ $DEVELOPER_OUTPUT
 - Only skip commit if changes are truly destructive/terrible
 - Use descriptive commit messages that explain what was attempted
 
-**IMPORTANT:** 
-- If you find issues, describe them clearly in your review AND in the commit message
-- If ALL tasks in the entire project are complete and verified, output: <VERIFIED_ALL_DONE>
-- Otherwise, describe what still needs to be done
+**IMPORTANT:**
+- DO NOT run tests - the Tester agent will do that next
+- If you find code quality issues, describe them clearly in your review AND in the commit message
+- Focus on code review, not test verification
 
-Be thorough but concise in your verification."
+Be thorough but concise in your code review."
 
     VERIFIER_LOGFILE="${LOGFILE}-verifier"
     echo "=== VERIFIER PROMPT ===" > $VERIFIER_LOGFILE
@@ -293,14 +326,129 @@ Be thorough but concise in your verification."
     # Run verifier
     time claude --model $CLAUDE_MODEL --dangerously-skip-permissions -p "$VERIFIER_PROMPT" 2>&1 | tee -a $VERIFIER_LOGFILE
 
-    # Check if verifier has confirmed all tasks are complete (only in output section)
-    if sed -n '/=== OUTPUT ===/,$p' $VERIFIER_LOGFILE | grep -q "^<VERIFIED_ALL_DONE>$"; then
+    # Extract verifier output for the tester
+    VERIFIER_OUTPUT=$(sed -n '/=== OUTPUT ===/,$p' $VERIFIER_LOGFILE)
+
+    echo -e "\033[32m==================================================================\033[0m"
+    echo -e "\033[32m== TESTING PHASE\033[0m"
+    echo -e "\033[32m==================================================================\033[0m"
+
+    # Determine if this is an acceptance test iteration (every 4th, with megathinking)
+    if [ $((LOOP_COUNTER % 4)) -eq 0 ]; then
+        ACCEPTANCE_TEST_MODE="
+**ACCEPTANCE TESTS (4th iteration - run these now):**
+Read the '## Acceptance Criteria' section in $plan_file.
+- Run each acceptance test (may include browser tests, integration tests)
+- Mark passing criteria with [x] in the plan file
+- If a previously-passing criterion now FAILS, add a bug task:
+  \`- [ ] [BUG] <description of what regressed>\`
+- Report which acceptance criteria pass/fail
+"
+    else
+        ACCEPTANCE_TEST_MODE="
+**ACCEPTANCE TESTS:** Skip this iteration (only run every 4th iteration).
+"
+    fi
+
+    # Define the tester prompt
+    TESTER_PROMPT="You are an expert QA engineer. Your job is to RUN TESTS and verify the code works.
+
+**DEVELOPER'S OUTPUT:**
+$DEVELOPER_OUTPUT
+
+**VERIFIER'S OUTPUT:**
+$VERIFIER_OUTPUT
+
+**PROJECT FILES:**
+- $plan_file (check '## Test Infrastructure' for test commands)
+- $plan_file (check '## Acceptance Criteria' for acceptance tests)
+
+**YOUR TASKS:**
+
+**1. UNIT TESTS (run every iteration):**
+Read '## Test Infrastructure' section in $plan_file for test commands.
+- Run the test suite (pytest, npm test, cargo test, etc.)
+- Run linters if configured
+- Report: which tests passed/failed
+- If tests FAIL, development cannot continue - report the failure clearly
+
+**2. TEST INFRASTRUCTURE CHECK:**
+If no '## Test Infrastructure' section exists OR no tests can be found:
+- Add task: \`- [ ] [INFRA] Set up test infrastructure\`
+- Report that TDD cannot proceed without test infrastructure
+$ACCEPTANCE_TEST_MODE
+**OUTPUT FORMAT:**
+- **<unit_tests>**: PASS or FAIL
+- **<unit_details>**: What tests ran, any failures
+- **<acceptance_tests>**: PASS, FAIL, SKIPPED, or NO_CRITERIA
+- **<acceptance_details>**: Which criteria checked (if applicable)
+- **<infrastructure>**: OK or MISSING
+- **<bugs_added>**: List any [BUG] tasks added for regressions
+- **<all_tests_pass>**: YES or NO
+
+**CRITICAL:** If unit tests fail, output <TESTS_FAILED> so the loop knows to stop.
+If ALL tasks in the plan are complete AND all tests pass, output: <VERIFIED_ALL_DONE>
+"
+
+    TESTER_LOGFILE="${LOGFILE}-tester"
+    echo "=== TESTER PROMPT ===" > $TESTER_LOGFILE
+    echo "$TESTER_PROMPT" >> $TESTER_LOGFILE
+    echo "=== END PROMPT ===" >> $TESTER_LOGFILE
+    echo "" >> $TESTER_LOGFILE
+    echo "=== OUTPUT ===" >> $TESTER_LOGFILE
+
+    # Run tester
+    echo "Running tester with $CLAUDE_MODEL model..."
+    time claude --model $CLAUDE_MODEL --dangerously-skip-permissions -p "$TESTER_PROMPT" 2>&1 | tee -a $TESTER_LOGFILE
+
+    # Check if tests failed
+    if sed -n '/=== OUTPUT ===/,$p' $TESTER_LOGFILE | grep -q "<TESTS_FAILED>"; then
+        echo -e "\033[31m==================================================================\033[0m"
+        echo -e "\033[31m== TESTS FAILED - Review tester output above\033[0m"
+        echo -e "\033[31m==================================================================\033[0m"
+        # Continue to next iteration - developer needs to fix the tests
+    fi
+
+    # Check if all done (tester confirmed)
+    if sed -n '/=== OUTPUT ===/,$p' $TESTER_LOGFILE | grep -q "^<VERIFIED_ALL_DONE>$"; then
         echo -e "\033[32m==================================================================\033[0m"
         echo -e "\033[32m== PROJECT COMPLETE - ALL TASKS VERIFIED!\033[0m"
         echo -e "\033[32m==================================================================\033[0m"
         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))
@@ -339,5 +487,31 @@ Be thorough but concise in your verification."
         echo -e "\033[32mNormal iteration timing - continuing...\033[0m"
     fi
 
+    # Check for PAUSE file - allows human intervention
+    if [ -f "PAUSE" ]; then
+        echo -e "\033[33m==================================================================\033[0m"
+        echo -e "\033[33m== PAUSED - Human intervention requested\033[0m"
+        echo -e "\033[33m==================================================================\033[0m"
+        echo -e "\033[33mDevelopment is paused. To continue:\033[0m"
+        echo -e "\033[33m  - Remove the PAUSE file: rm PAUSE\033[0m"
+        echo -e "\033[33m  - Add feedback in $WORKING_DIR/FEEDBACK.md (optional)\033[0m"
+        echo -e "\033[33mWaiting...\033[0m"
+        while [ -f "PAUSE" ]; do
+            sleep 5
+        done
+        echo -e "\033[32mResuming development...\033[0m"
+
+        # Check if feedback was added
+        if [ -f "$WORKING_DIR/FEEDBACK.md" ]; then
+            echo -e "\033[36mFEEDBACK.md detected - will be processed in next iteration\033[0m"
+        fi
+    fi
+
+    # Archive FEEDBACK.md after it's been processed (move to logs)
+    if [ -n "$feedback_file" ] && [ -f "$feedback_file" ]; then
+        mv "$feedback_file" "logs/FEEDBACK-processed-$(date +%Y%m%d_%H%M%S).md"
+        echo -e "\033[36mFEEDBACK.md archived after processing\033[0m"
+    fi
+
     sleep 1
 done

package/package.json

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