feat(ralph-wizard): add auto-start option and improve /init timing

- Research agent now explores local project first (CLAUDE.md priority)
- Added {WORKING_DIR} placeholder to research prompt
- New "Auto-Start After Plan" checkbox in advanced options
- Increased /init timeout from 10s to 3 minutes
- Added 3s delay after /init completes for stability

chore: bump version to 0.1409

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -16,7 +16,7 @@ When user says "COM":
 1. Increment version in BOTH `package.json` AND `CLAUDE.md`
 2. Run: `git add -A && git commit -m "chore: bump version to X.XXXX" && git push && npm run build && systemctl --user restart claudeman-web`
 
-**Version**: 0.1408 (must match `package.json`)
+**Version**: 0.1409 (must match `package.json`)
 
 ## Project Overview
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeman",
-  "version": "0.1408",
+  "version": "0.1409",
   "description": "The missing control plane for Claude Code - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",

src/plan-orchestrator.ts

@@ -814,16 +814,18 @@ Check \`${caseDir}/ralph-wizard/research/result.json\` for:
     this.runningSessions.add(session);
 
     try {
-      const prompt = RESEARCH_AGENT_PROMPT.replace('{TASK}', taskDescription);
+      const prompt = RESEARCH_AGENT_PROMPT
+        .replace('{TASK}', taskDescription)
+        .replace('{WORKING_DIR}', this.workingDir);
 
-      onProgress?.('research', 'Starting research agent (web search + codebase exploration)...');
+      onProgress?.('research', 'Starting research agent (local project + web search)...');
 
       // Periodic progress updates showing elapsed time with contextual messages
       const researchPhases = [
-        { min: 0, msg: 'Searching for relevant GitHub repos and documentation...' },
+        { min: 0, msg: 'Reading CLAUDE.md and exploring project structure...' },
-        { min: 30, msg: 'Exploring official docs and best practice guides...' },
+        { min: 30, msg: 'Analyzing existing code patterns and conventions...' },
-        { min: 60, msg: 'Analyzing codebase patterns and conventions...' },
+        { min: 60, msg: 'Searching for relevant documentation and examples...' },
-        { min: 120, msg: 'Synthesizing findings and recommendations...' },
+        { min: 120, msg: 'Synthesizing local and external findings...' },
         { min: 180, msg: 'Compiling research results (complex tasks take time)...' },
         { min: 300, msg: 'Almost done - finalizing enriched task description...' },
       ];

src/prompts/research-agent.ts

@@ -4,7 +4,7 @@
  * Gathers external resources, codebase patterns, and technical context
  * before other agents analyze the task.
  *
- * Placeholders: {TASK}
+ * Placeholders: {TASK}, {WORKING_DIR}
  */
 
 export const RESEARCH_AGENT_PROMPT = `You are a Research Specialist preparing context for an implementation task. Your job is to gather all relevant information that will help the development team succeed.
@@ -15,40 +15,100 @@ Research and gather comprehensive context for implementing this task:
 ## TASK DESCRIPTION
 {TASK}
 
+## WORKING DIRECTORY
+{WORKING_DIR}
+
 ## INSTRUCTIONS
 Perform thorough research across multiple sources:
 
-### 1. WEB RESEARCH (CRITICAL)
+### 1. LOCAL PROJECT EXPLORATION (DO THIS FIRST)
+Explore the working directory to understand the existing project:
+
+**PRIORITY: Read CLAUDE.md First!**
+If a CLAUDE.md file exists in the working directory, READ IT IMMEDIATELY. This file contains:
+- Project-specific instructions and conventions
+- Build and test commands
+- Architecture overview
+- Important patterns and gotchas
+- Files and directories to focus on
+
+**Project Structure:**
+- List files and directories to understand the project layout
+- Look for package.json, tsconfig.json, Cargo.toml, requirements.txt, etc. to identify tech stack
+- Also check README.md or docs/ for additional documentation
+- Identify the main source directories (src/, lib/, app/, etc.)
+
+**Existing Code Patterns:**
+- Search for similar features or functionality already implemented
+- Identify coding conventions (naming, file organization, module patterns)
+- Look at existing tests to understand testing patterns
+- Check for configuration files, environment setup, types/interfaces
+
+**Key Files to Examine:**
+- Entry points (index.ts, main.py, App.tsx, etc.)
+- Type definitions and interfaces
+- Utility functions and shared code
+- Database models or schemas if applicable
+
+USE THESE TOOLS:
+- \`Glob\` to find files by pattern (e.g., "**/*.ts", "src/**/*.tsx")
+- \`Grep\` to search for specific patterns, function names, or imports
+- \`Read\` to examine file contents
+- Look at the most recently modified files - they're likely relevant
+
+### 2. WEB RESEARCH
 Use web search to find:
-- **GitHub repositories** that implement similar features or solve similar problems
+- **Official documentation** for technologies used in the project
-- **Official documentation** for any technologies, APIs, or frameworks mentioned
+- **GitHub repositories** that implement similar features
-- **Claude Code documentation** if the task involves Claude Code features
+- **Best practice guides** for the tech stack identified
-- **Best practice guides** and tutorials from reputable sources
+- **Stack Overflow answers** for specific implementation questions
-- **Stack Overflow answers** for common implementation patterns
 
 Focus your web search on:
-- How others have solved similar problems
+- How others have solved similar problems with the same tech stack
-- Common pitfalls and gotchas
+- Common pitfalls and gotchas for the specific technologies
-- Library/package recommendations
+- Library/package recommendations compatible with the project
 - API usage examples
 
-### 2. CODEBASE EXPLORATION
-If the task involves modifying an existing codebase, explore it to understand:
-- Existing patterns and conventions used
-- Similar features already implemented
-- File organization and architecture
-- Test patterns and coverage
-
 ### 3. TECHNICAL ANALYSIS
 Based on your research:
-- Recommend the best technical approach
+- Recommend the best approach that fits the existing codebase style
-- Identify potential challenges before they become blockers
+- Identify files that will need to be modified or created
-- Suggest useful libraries or tools
+- Suggest where new code should live based on existing structure
 - Note any compatibility or integration concerns
 
 ## OUTPUT FORMAT
 Return ONLY a JSON object:
 {
+  "projectContext": {
+    "techStack": ["TypeScript", "React", "Node.js", ...],
+    "projectType": "web-app|cli|library|api|monorepo|...",
+    "buildSystem": "npm|yarn|pnpm|cargo|pip|...",
+    "testFramework": "vitest|jest|pytest|...",
+    "keyDirectories": {
+      "source": "src/",
+      "tests": "test/",
+      "config": "..."
+    },
+    "entryPoints": ["src/index.ts", ...],
+    "hasDocumentation": true|false,
+    "documentationNotes": "Summary of CLAUDE.md or README if found"
+  },
+  "existingPatterns": [
+    {
+      "pattern": "Pattern name (e.g., 'EventEmitter for async communication')",
+      "location": "src/events/*.ts",
+      "example": "Brief code example or file reference",
+      "relevance": "Why this pattern matters for the task"
+    }
+  ],
+  "relevantFiles": [
+    {
+      "path": "src/components/Auth.tsx",
+      "purpose": "What this file does",
+      "relevance": "Why it's relevant to the task",
+      "shouldModify": true|false
+    }
+  ],
   "externalResources": [
     {
       "type": "github|documentation|tutorial|article|stackoverflow",
@@ -58,33 +118,26 @@ Return ONLY a JSON object:
       "keyInsights": ["Insight 1", "Insight 2"]
     }
   ],
-  "codebasePatterns": [
-    {
-      "pattern": "Pattern name (e.g., 'Repository pattern for data access')",
-      "location": "src/repositories/*.ts",
-      "relevance": "Why this pattern matters for the task"
-    }
-  ],
   "technicalRecommendations": [
-    "Use approach X because...",
+    "Use the existing EventEmitter pattern from src/events/ for...",
-    "Consider library Y for..."
+    "Follow the component structure in src/components/..."
   ],
   "potentialChallenges": [
-    "Watch out for X when implementing Y",
+    "The existing auth system uses X, need to integrate with...",
-    "Common gotcha: ..."
+    "Watch out for Y when modifying Z"
   ],
-  "recommendedTools": [
+  "suggestedApproach": {
-    {
+    "summary": "Brief 2-3 sentence approach recommendation",
-      "name": "library-name",
+    "newFiles": ["src/features/new-feature.ts", ...],
-      "purpose": "What it does",
+    "modifyFiles": ["src/index.ts", ...],
-      "reason": "Why it's recommended for this task"
+    "testFiles": ["test/new-feature.test.ts", ...]
-    }
+  },
-  ],
+  "enrichedTaskDescription": "A detailed version of the original task, enriched with specific file paths, existing patterns to follow, and technical details from your exploration. Should reference actual files and patterns found in the codebase."
-  "enrichedTaskDescription": "A more detailed version of the original task, enriched with context from your research. This should include specific technical details, file locations, API endpoints, library versions, etc. that will help other agents understand exactly what needs to be done."
 }
 
 CRITICAL REQUIREMENTS:
-1. ACTUALLY USE WEB SEARCH to find external resources - don't make them up
+1. ALWAYS explore the local project FIRST - understand what exists before searching online
-2. Include real URLs when found via web search
+2. Reference ACTUAL files and patterns found in the codebase, not hypothetical ones
-3. The enrichedTaskDescription should be 2-3x more detailed than the original
+3. The enrichedTaskDescription MUST include specific file paths and patterns from the project
-4. Be specific - vague research is useless research`;
+4. Use Glob/Grep/Read tools to actually explore - don't guess about project structure
+5. If web search finds useful resources, include real URLs`;

src/web/public/app.js

@@ -2642,6 +2642,7 @@ class ClaudemanApp {
       maxIterations: 10,
       caseName: document.getElementById('quickStartCase')?.value || 'testcase',
       enableRespawn: true,
+      autoStart: false,         // Auto-start loop after plan generation
       // Plan generation fields
       generatedPlan: null,
       planGenerated: false,
@@ -2656,6 +2657,9 @@ class ClaudemanApp {
     document.getElementById('ralphTaskDescription').value = '';
     document.getElementById('ralphCompletionPhrase').value = 'COMPLETE';
     this.selectIterationPreset(10);
+    // Reset auto-start checkbox (off by default)
+    const autoStartEl = document.getElementById('ralphAutoStart');
+    if (autoStartEl) autoStartEl.checked = false;
 
     // Populate case selector
     this.populateRalphCaseSelector();
@@ -3172,6 +3176,15 @@ class ClaudemanApp {
       this.renderPlanEditor();
       this.updateDetailLevelButtons();
 
+      // Check for auto-start
+      if (this.ralphWizardConfig.autoStart) {
+        console.log('[RalphWizard] Auto-start enabled, starting loop automatically...');
+        this.showToast('Plan complete! Auto-starting Ralph Loop...', 'success');
+        // Small delay to let user see the plan briefly
+        await new Promise(r => setTimeout(r, 1500));
+        this.startRalphLoop();
+      }
+
     } catch (err) {
       // Stop timer
       if (this.planLoadingTimer) {
@@ -4014,6 +4027,7 @@ class ClaudemanApp {
 
     // Read advanced options (respawn disabled by default for Ralph Loops)
     config.enableRespawn = document.getElementById('ralphEnableRespawn')?.checked ?? false;
+    config.autoStart = document.getElementById('ralphAutoStart')?.checked ?? false;
 
     // Close wizard
     this.closeRalphWizard();
@@ -4204,29 +4218,39 @@ class ClaudemanApp {
         if (!initRes.ok) {
           console.warn('[RalphWizard] Failed to send /init, continuing anyway...');
         } else {
-          // Wait for /init to complete (look for ready indicator or timeout)
+          // Wait for /init to complete - can take up to 3 minutes for large CLAUDE.md files
-          console.log('[RalphWizard] Waiting for /init to complete...');
+          console.log('[RalphWizard] Waiting for /init to complete (can take up to 3 minutes)...');
           let initComplete = false;
-          for (let attempt = 0; attempt < 20; attempt++) {
+          const initMaxAttempts = 180; // 3 minutes at 1 second intervals
-            await new Promise(r => setTimeout(r, 500));
+          for (let attempt = 0; attempt < initMaxAttempts; attempt++) {
+            await new Promise(r => setTimeout(r, 1000));
             try {
               const statusRes = await fetch(`/api/sessions/${sessionId}`);
               const statusData = await statusRes.json();
-              // /init is complete when we see the prompt indicator (❯) or status is ready
+              const termBuf = statusData?.terminalBuffer || '';
-              if (statusData.status === 'ready' || statusData.lastOutput?.includes('❯')) {
+              // /init is complete when we see the prompt indicator (❯) and not working
-                console.log('[RalphWizard] /init complete, Claude now has research context.');
+              const hasPrompt = termBuf.includes('❯');
+              const isIdle = !statusData.isWorking;
+              if (hasPrompt && isIdle) {
+                console.log(`[RalphWizard] /init complete after ${attempt + 1}s, Claude now has research context.`);
                 initComplete = true;
                 break;
               }
+              // Log progress every 15 seconds
+              if ((attempt + 1) % 15 === 0) {
+                console.log(`[RalphWizard] Still waiting for /init... ${attempt + 1}s elapsed (isWorking=${statusData.isWorking})`);
+              }
             } catch (e) {
               console.warn('[RalphWizard] Status check error:', e);
             }
           }
           if (!initComplete) {
-            console.log('[RalphWizard] /init may still be running, proceeding anyway...');
+            console.warn('[RalphWizard] /init did not complete within 3 minutes, proceeding anyway...');
+            this.showToast('/init took longer than expected, prompt may not have full context', 'warning');
           }
-          // Small delay after /init
+          // Delay after /init to let Claude settle
-          await new Promise(r => setTimeout(r, 1000));
+          console.log('[RalphWizard] Adding 3s delay after /init...');
+          await new Promise(r => setTimeout(r, 3000));
         }
       }
 

src/web/public/index.html

@@ -1097,6 +1097,14 @@
             <details class="advanced-options">
               <summary>Advanced Options</summary>
               <div class="advanced-options-content">
+                <div class="form-row form-row-switch">
+                  <label>Auto-Start After Plan</label>
+                  <label class="switch">
+                    <input type="checkbox" id="ralphAutoStart">
+                    <span class="slider"></span>
+                  </label>
+                  <span class="form-hint">Automatically start the loop when plan generation completes</span>
+                </div>
                 <div class="form-row form-row-switch">
                   <label>Enable Respawn</label>
                   <label class="switch">