fix(orchestrator): comprehensive workflow engine overhaul - 8 major fixes

Complete redesign of agent orchestrator workflow engine to fix critical bugs
in todo tracking, message alternation, and continuation guidance. Evolved from
rigid "force tools" approach to intelligent context-aware orchestration that
follows the orchestrator.txt flow diagram correctly.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUMMARY OF FIXES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Fix #1: Todo Workflow Infinite Loops & Update-Before-Create**
Agent tried to update todos before creating list, causing crashes and loops.
Graduated interventions gave contradictory instructions.

Solution:
- Added CRITICAL ERROR TO AVOID section in todo_operations tool
- Visual step-by-step workflow added to tool description
- Rewrote all 3 graduated intervention levels with consistent guidance
- Implemented proper Continue Flag pattern matching orchestrator.txt
- Added shouldContinueAfterChecks flag for correct workflow flow

Result: No more update-before-create crashes, workflow matches design exactly

**Fix #2: Response Loops (Agent Repeating Same Text)**
Agent stuck repeating same response infinitely when todos incomplete.
pendingAutoContinueMessage was set but never injected.

Solution:
- Inject pendingAutoContinueMessage at iteration start
- Call injectAutoContinueIfTodosIncomplete() when no tools + active todos
- Graduated intervention (Level 1 → 2 → 3) now works as designed
- Remove last assistant message to prevent loops

Result: No more infinite response loops, graduated intervention working

**Fix #3: Tool Result Infinite Loop (read_tool_result Stuck)**
Agent stuck seeing SAME tool result chunk repeatedly for 15+ iterations.
TOOL_RESULT_CHUNK messages preserved across iterations incorrectly.

Solution:
- Removed preservation logic for TOOL_RESULT_CHUNK messages
- Chunks now appear once when tool executes
- Agent must call read_tool_result to get more chunks
- Proper pagination flow restored

Result: No more chunk re-injection loops, clean pagination behavior

**Fix #4: Message Alternation Violations**
Multiple consecutive assistant messages broke Claude API compatibility.
Evolved through 3 iterations: Rigid → Binary → Flexible → Context-Aware

Final Solution - Todo-Aware Continuation Guidance:
- 4 guidance variants: (has todos YES/NO) × (tools used YES/NO)
- With todos + tools: "MANDATORY TODO WORKFLOW: mark → work → complete"
- With todos + no tools: "You have incomplete todos - MUST follow workflow"
- Without todos + tools: "Need more data? → tools. Have enough? → respond"
- Without todos + no tools: "Already answered? Use tools for follow-up"

Result: Fixes consecutive messages, allows flexibility, enforces discipline

**Fix #5: Planning Loop False Positives**
Planning loop detector flagged normal workflow (mark todo → work → complete)
as infinite loop because it saw consecutive todo_operations calls.

Solution:
- Added isTodoCompletionCall() helper function
- Marking todos complete now counts as progress
- Only flag as loop if NO work tools AND NO todo completions

Result: Normal workflow allowed, actual loops still detected

**Fix #6: Stale Todo List (Workflow Stopped Early)**
Workflow stopped when todos incomplete because orchestrator saw stale "all
complete" state. currentTodoList only updated after tool execution.

Solution:
- Read fresh todo list from MCP BEFORE every workflow check
- Only if currentTodoList.count > 0 (known active list exists)
- TodoReminderInjector: Clarified workflow guidance wording
- Makes explicit: mark in-progress → DO THE WORK → mark completed

Result: Workflows continue correctly, no premature stops, fresh state accurate

**Fix #7: Duplicate Tool Cards in Streaming Mode**
Tool cards appeared twice in UI - once from streaming, once from main loop.

Solution:
- Skip tool message creation in main loop when streaming active
- Check streamContinuation - if present, streaming created messages
- Non-streaming unchanged

Result: Clean UI, no duplicate cards

**Fix #8: Web Research Error Card Clutter**
Red error cards for expected situations (empty pages, no results).
VectorRAGError helpful messages wrapped with confusing text.

Solution:
- Pass through VectorRAGError messages without wrapping
- Handle partial failures gracefully (some sources succeed = green card)
- Only show error if ALL sources fail

Result: Clean UI, helpful guidance preserved

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TESTING RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Simple workflow (3 stories): All tracked, completed, brief summary
✅ Complex workflow (3 research tasks): All tracked, completed, brief summary
✅ Fresh todo reads detect incomplete todos correctly
✅ Agent doesn't repeat work in final summary
✅ No more response loops or chunk re-injection
✅ Planning loop detector allows normal workflow
✅ Context-aware continuation guidance works
✅ Streaming mode: no duplicate tool cards
✅ Web research: clean error handling
✅ Build: PASS (all commits)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DOCUMENTATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Added comprehensive documentation:
- project-docs/AGENT_ORCHESTRATOR.md (complete architecture)
  * Complete workflow flow diagram (Mermaid)
  * Detailed 8-step decision tree
  * Fresh todo state read documentation
  * Continuation priority table
  * All fixes documented with root causes
  * Known Issues updated with resolutions

- ai-assisted/2026-01-04/workflow-alternation-fix/
  * CONTINUATION_PROMPT.md (session handoff)
  * AGENT_PLAN.md (remaining work breakdown)

- .github/copilot-instructions.md
  * Added isBackground=false requirement (CRITICAL)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FILES MODIFIED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Primary:
- Sources/APIFramework/AgentOrchestrator.swift
  * Fresh todo reads before workflow checks
  * Context-aware continuation guidance system
  * Graduated intervention injection fixed
  * Planning loop detection improvements
  * Duplicate tool card fix for streaming

- Sources/MCPFramework/TodoReminderInjector.swift
  * Todo-aware workflow guidance (4 variants)
  * Clear final message guidance when all tasks complete

- Sources/MCPFramework/Tools/TodoOperationsTool.swift
  * CREATE FIRST requirement documentation
  * Visual step-by-step workflow added

- Sources/ConfigurationSystem/SimpleSystemPromptManager.swift
  * Todo workflow discipline documentation

Supporting:
- Sources/MCPFramework/Tools/WebResearchTool.swift
  * VectorRAGError pass-through without wrapping

- Sources/ConversationEngine/WebResearchService.swift
  * Partial failure handling (some sources succeed)

Documentation:
- project-docs/AGENT_ORCHESTRATOR.md (new + updated)
- ai-assisted/2026-01-04/workflow-alternation-fix/* (new)
- .github/copilot-instructions.md (updated)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ARCHITECTURAL IMPROVEMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Context-Aware Guidance System:
- 4 guidance variants adapt to workflow state
- Based on: (has incomplete todos?) × (tools called?)
- Each variant provides specific, actionable instructions
- Prevents workflow violations through clear communication

Fresh State Reads:
- Todo list read fresh from MCP before every workflow check
- Prevents stale cache bugs that caused premature stops
- Only reads when active todo list exists (performance optimization)

Graduated Intervention Pressure:
- Level 1: Polite reminder about incomplete todos
- Level 2: Warning about loop behavior
- Level 3: Final warning before failure
- Escalates pressure if agent keeps ignoring todos

Proper Continue Flag Pattern:
- Matches orchestrator.txt flow diagram exactly
- Can be set by: tool execution, incomplete todos, workflow mode
- Priority ordering ensures correct continuation behavior

Unified Todo Workflow Discipline:
- All guidance sources enforce same workflow
- CREATE list first, THEN mark in-progress
- Mark in-progress → DO THE WORK → mark completed
- Never skip status updates

Code Quality:
- Eliminated ~100 lines of redundant code
- Cleaner separation: streaming vs non-streaming paths
- Better error handling and logging

Result: Intelligent orchestrator that adapts guidance based on workflow
context while enforcing todo discipline and preventing loops.

Author: fewtarius

.github/copilot-instructions.md

@@ -155,6 +155,33 @@ Ready to end session? Press Enter:"
 
 ---
 
+## CRITICAL: run_in_terminal MUST NEVER USE isBackground=true
+
+**❌ NEVER DO THIS:**
+```bash
+run_in_terminal(command: "make build", isBackground: true)  # WRONG! Causes silent failures
+run_in_terminal(command: "git commit", isBackground: true)   # WRONG! Command gets cancelled
+```
+
+**✅ ALWAYS DO THIS:**
+```bash
+run_in_terminal(command: "make build", isBackground: false)  # CORRECT
+run_in_terminal(command: "git commit", isBackground: false)  # CORRECT
+```
+
+**WHY:**
+- `isBackground=true` causes commands to be cancelled/interrupted
+- You won't see output or know if command succeeded
+- Git commits, builds, and all other commands REQUIRE `isBackground=false`
+- This is a HARD REQUIREMENT - violations cause session failure
+
+**THE RULE:**
+- ALWAYS set `isBackground: false` for ALL commands
+- NEVER use `isBackground: true` for ANY command
+- If unsure, default to `false`
+
+---
+
 ## SAM-SPECIFIC DEVELOPMENT
 
 ### Build System

Sources/APIFramework/AgentOrchestrator.swift

@@ -229,11 +229,29 @@ public class SimpleSystemPromptManager: ObservableObject {
 
         ## WORKFLOW TRACKING
         - **For multi-step tasks** (series of stories, multiple edits, sequential analysis, debugging, development, etc.):
-          * Create todos: `{"name":"todo_operations","arguments":{"operation":"write","todoList":[{"id":1,"title":"Task 1","description":"...","status":"not-started"}]}}`
-          * Mark complete: `{"name":"todo_operations","arguments":{"operation":"update","todoUpdates":[{"id":1,"status":"completed"}]}}`
-          * This allows the system to track your progress and remind you of remaining items
-          * Mark each todo as completed IMMEDIATELY after finishing it - do not continue same task
-          * Example: User requests 7 stories → create 7 todos, write each story, mark each complete, then move to next
+          
+          **STEP 1 - Create the todo list (first time only):**
+          * `{"name":"todo_operations","arguments":{"operation":"write","todoList":[{"id":1,"title":"Task 1","description":"...","status":"not-started"}]}}`
+          * Set ALL todos as "not-started" when creating the list
+          
+          **STEP 2 - Mark one todo as in-progress:**
+          * `{"name":"todo_operations","arguments":{"operation":"update","todoUpdates":[{"id":1,"status":"in-progress"}]}}`
+          * Only do this AFTER the list exists (after STEP 1)
+          
+          **STEP 3 - Do the work:**
+          * Execute the actual task using appropriate tools
+          
+          **STEP 4 - Mark todo complete:**
+          * `{"name":"todo_operations","arguments":{"operation":"update","todoUpdates":[{"id":1,"status":"completed"}]}}`
+          * Do this IMMEDIATELY after finishing each task
+          
+          **STEP 5 - Repeat:**
+          * Go back to STEP 2 for next todo
+          
+          **CRITICAL - Common mistake:**
+          * ❌ WRONG: Try to mark a todo in-progress before creating the list
+          * ✅ CORRECT: Create list with 'write' operation FIRST, then update with 'update'
+          
         - **Todo list format**: Array of objects with id, title, description, status ("not-started", "in-progress", "completed")
         - **Why use todos**: Enables progress tracking across long workflows, prevents stopping early
         """

Sources/ConfigurationSystem/SimpleSystemPromptManager.swift

@@ -520,59 +520,32 @@ private static func buildSAMSpecificPatterns() -> String {
 
     **Sequential Lists:** One item per message, emit continue after each (except last → complete).
 
-    MULTI-STEP REQUESTS - TODO LIST WORKFLOW (MANDATORY):
-
-    For multi-step tasks, you MUST use the todo_operations tool to plan and track progress:
-
-    **STEP 1 - CREATE TODO LIST:**
-    - Use todo_operations(write) to create a structured plan
-    - Break work into actionable, trackable steps
-    - Set the FIRST task as "in-progress"
-
-    **STEP 2 - WORK ON EACH TODO:**
-    - Before starting ANY todo: Ensure it is marked "in-progress"
-    - Execute work tools (web_operations, file_operations, terminal_operations)
-    - Produce tangible results (lists, files, charts, data)
-    - Mark the todo "completed" IMMEDIATELY after finishing
-    - Move to next todo and repeat
-
-    **CRITICAL TODO WORKFLOW RULES:**
-    - ALWAYS mark exactly ONE todo "in-progress" before starting work on it
-    - ALWAYS mark a todo "completed" immediately after finishing (not in batches)
-    - NEVER work on a task without first marking it "in-progress"
-    - NEVER leave multiple todos in "in-progress" state
-    - Update todos frequently - the user sees your progress through the todo list
-
-    **CORRECT TODO SEQUENCE:**
-    1. todo_operations(write) → create plan with first item in-progress
-    2. Execute work tool → produce tangible result
-    3. todo_operations(update: completed) → mark current done
-    4. todo_operations(update: in-progress) → mark next task started
-    5. Repeat until all complete
-
-    **FAILURE PATTERNS TO AVOID:**
-    - Creating todos but never calling todo_operations(update) to mark them complete = FAILURE
-    - Writing "Task 1 complete" in your response instead of calling the tool = FAILURE
-    - Doing work without calling todo_operations(update) afterward = FAILURE
-    - Restating the todo list in plain text instead of calling the tool = FAILURE
-    - Describing progress verbally but not updating the actual todo list = FAILURE
-
-    **CRITICAL ANTI-PATTERN:**
-    Saying "I've completed brainstorming" or "Task 1 is done" in your text response
-    is NOT the same as calling todo_operations(update) to mark it completed.
-    You MUST call the tool - the system cannot infer status from your text.
-
-    **PLANNING LOOP DETECTION:**
-    - If you've outlined the same plan 2+ times, you are stuck
-    - STOP planning and immediately execute a work tool
-
-    **TANGIBLE OUTPUT REQUIRED:**
-    - Each step must produce tool-generated results (lists, files, charts, data)
-    - Text summaries alone are NOT progress - use tools to produce deliverables
-
-    **Collaboration Override:** If user asks to "check with me first" or "collaborate", wait for their response before proceeding.
-
-    **Tool Results in History:** Previous tool outputs are YOUR results - use them, don't re-call tools.
+    MULTI-STEP REQUESTS - TODO LIST WORKFLOW:
+
+    **When to use todos:** Multi-step tasks that benefit from visible progress tracking
+
+    **Starting fresh (no todos yet):**
+    1. FIRST: Create todo list with todo_operations(operation: "write", todoList: [...])
+       - Set first todo: "in-progress"
+       - Set remaining todos: "not-started"
+    2. Then proceed with workflow below
+
+    **Working with existing todos:**
+    1. Do the work for current in-progress todo
+    2. Mark it completed: todo_operations(operation: "update", todoUpdates: [{"id": X, "status": "completed"}])
+    3. Mark next todo in-progress: todo_operations(operation: "update", todoUpdates: [{"id": Y, "status": "in-progress"}])
+    4. Repeat until all complete
+
+    **CRITICAL RULES:**
+    - ALWAYS create todos FIRST before trying to update them (NEVER call update when no todos exist)
+    - You MUST call todo_operations(update) to change todo status - the system cannot infer status from your text
+    - When completing a todo: Mark it done with the tool, then move to next todo - do NOT repeat the work in your response
+    - Each todo gets ONE completion response - mark done and move forward
+
+    **Anti-duplication:**
+    - After completing Todo 1: Mark complete, start Todo 2, work on Todo 2
+    - Do NOT: Complete Todo 1, mark done, then re-summarize Todo 1's results again
+    - Tool call = progress indicator, not invitation to repeat output
 
     **Before Complete:** Verify ALL requested items delivered. If user asked for N things, confirm N things done.
 

Sources/ConfigurationSystem/SystemPromptConfiguration.swift

@@ -0,0 +1,195 @@
+@@ -360,20 +360,6 @@
+         - **Not give up unless request genuinely cannot be fulfilled**
+ 
+         **Continue working until the user's request is completely resolved. Only stop when certain the task is complete. Do not stop when encountering uncertainty — research or deduce the most reasonable approach and continue.**
+-
+-        **Handling Partial Success:**
+-        - When some tool calls succeed and others fail, USE THE SUCCESSFUL DATA
+-        - Partial data is often sufficient to make progress - do not wait for perfect information
+-        - Do not focus on failures; extract maximum value from successes
+-        - Multiple failed attempts do not mean the tool is broken - adapt your approach
+-
+-        **Adaptation Strategy:**
+-        - If a tool fails, immediately try an alternative approach:
+-          * research_operations fails → try web_operations with operation='fetch'
+-          * web_operations fails → try different keywords or file_operations
+-          * terminal command fails → try alternative commands or approaches
+-        - NEVER ask the user "what should I do?" when a tool fails
+-        - Adapt autonomously and continue working toward the goal
+         """
+     }
+ 
+@@ -463,7 +449,7 @@
+         **Validation:** Read files back, count items processed, check for errors.
+ 
+         **Conversational Partner Protocol:**
+-        - After completing work, always provide a brief recap of what was accomplished.
++        - After signaling ``, always provide a brief recap of what was accomplished.
+         - Explicitly invite further questions, suggestions, or next steps ("Is there anything else you'd like to do?").
+         - If no immediate input from user, remain in a conversational 'ready' state, prepared to respond promptly to new requests.
+         - Never terminate the conversation abruptly—always end with a clear invitation for continued engagement.
+@@ -476,15 +462,7 @@
+         ## Communication Protocol
+         **During work:** Provide brief progress updates. Where appropriate, invite user input or confirmation—especially before proceeding to the next step in multi-phase tasks, or when user review may be beneficial.
+ 
+-        **When complete:** Summarize accomplishments, present results, and ask if the user wants to review, continue, or discuss further.
+-
+-        ## System Reminders
+-
+-        During execution, you will receive <system-reminder> tags with context-specific guidance:
+-        - These are time-sensitive instructions for the current iteration
+-        - They provide continuation guidance, todo updates, or process instructions
+-        - Pay close attention to system reminders - they guide workflow progression
+-        - Follow system reminder instructions carefully
++        **When complete:** Summarize accomplishments, present results, and ask if the user wants to review, continue, or discuss further before emitting `` and stopping, unless the user prefers uninterrupted execution.
+ 
+         **When blocked:** Explain what you tried, what's blocking you, and request specific information or guidance from the user.
+ 
+@@ -540,32 +518,57 @@
+     - Never call the think tool twice in a row; if you do, immediately switch to tool-based execution.
+     - Planning alone is not progress—after thinking, you MUST produce a tool-generated, user-facing deliverable.
+ 
+-    MULTI-STEP REQUESTS - TODO LIST WORKFLOW:
+-
+-    **When to use todos:** Multi-step tasks that benefit from visible progress tracking
+-
+-    **Starting fresh (no todos yet):**
+-    1. FIRST: Create todo list with todo_operations(operation: "write", todoList: [...])
+-       - Set first todo: "in-progress"
+-       - Set remaining todos: "not-started"
+-    2. Then proceed with workflow below
+-
+-    **Working with existing todos:**
+-    1. Do the work for current in-progress todo
+-    2. Mark it completed: todo_operations(operation: "update", todoUpdates: [{"id": X, "status": "completed"}])
+-    3. Mark next todo in-progress: todo_operations(operation: "update", todoUpdates: [{"id": Y, "status": "in-progress"}])
+-    4. Repeat until all complete
+-
+-    **CRITICAL RULES:**
+-    - ALWAYS create todos FIRST before trying to update them (NEVER call update when no todos exist)
+-    - You MUST call todo_operations(update) to change todo status - the system cannot infer status from your text
+-    - When completing a todo: Mark it done with the tool, then move to next todo - do NOT repeat the work in your response
+-    - Each todo gets ONE completion response - mark done and move forward
+-
+-    **Anti-duplication:**
+-    - After completing Todo 1: Mark complete, start Todo 2, work on Todo 2
+-    - Do NOT: Complete Todo 1, mark done, then re-summarize Todo 1's results again
+-    - Tool call = progress indicator, not invitation to repeat output
++    **Sequential Lists:** One item per message, emit continue after each (except last → complete).
++
++    MULTI-STEP REQUESTS - TODO LIST WORKFLOW (MANDATORY):
++
++    For multi-step tasks, you MUST use the todo_operations tool to plan and track progress:
++
++    **STEP 1 - CREATE TODO LIST:**
++    - Use todo_operations(write) to create a structured plan
++    - Break work into actionable, trackable steps
++    - Set the FIRST task as "in-progress"
++
++    **STEP 2 - WORK ON EACH TODO:**
++    - Before starting ANY todo: Ensure it is marked "in-progress"
++    - Execute work tools (web_operations, file_operations, terminal_operations)
++    - Produce tangible results (lists, files, charts, data)
++    - Mark the todo "completed" IMMEDIATELY after finishing
++    - Move to next todo and repeat
++
++    **CRITICAL TODO WORKFLOW RULES:**
++    - ALWAYS mark exactly ONE todo "in-progress" before starting work on it
++    - ALWAYS mark a todo "completed" immediately after finishing (not in batches)
++    - NEVER work on a task without first marking it "in-progress"
++    - NEVER leave multiple todos in "in-progress" state
++    - Update todos frequently - the user sees your progress through the todo list
++
++    **CORRECT TODO SEQUENCE:**
++    1. todo_operations(write) → create plan with first item in-progress
++    2. Execute work tool → produce tangible result
++    3. todo_operations(update: completed) → mark current done
++    4. todo_operations(update: in-progress) → mark next task started
++    5. Repeat until all complete
++
++    **FAILURE PATTERNS TO AVOID:**
++    - Creating todos but never calling todo_operations(update) to mark them complete = FAILURE
++    - Writing "Task 1 complete" in your response instead of calling the tool = FAILURE
++    - Doing work without calling todo_operations(update) afterward = FAILURE
++    - Restating the todo list in plain text instead of calling the tool = FAILURE
++    - Describing progress verbally but not updating the actual todo list = FAILURE
++
++    **CRITICAL ANTI-PATTERN:**
++    Saying "I've completed brainstorming" or "Task 1 is done" in your text response
++    is NOT the same as calling todo_operations(update) to mark it completed.
++    You MUST call the tool - the system cannot infer status from your text.
++
++    **PLANNING LOOP DETECTION:**
++    - If you've outlined the same plan 2+ times, you are stuck
++    - STOP planning and immediately execute a work tool
++
++    **TANGIBLE OUTPUT REQUIRED:**
++    - Each step must produce tool-generated results (lists, files, charts, data)
++    - Text summaries alone are NOT progress - use tools to produce deliverables
+ 
+     **Collaboration Override:** If user asks to "check with me first" or "collaborate", wait for their response before proceeding.
+ 
+@@ -599,6 +602,63 @@
+     """
+ }
+ 
++    /// Builds Think Tool Guidance section - Consolidated from multiple scattered sections.
++    private static func buildThinkToolGuidance() -> String {
++        return """
++        ### Think Tool (Supplemental)
++
++        Shows "Thinking..." to user for complex reasoning. Use sparingly - execution matters more.
++        Avoid think tool loops: plan once, execute, don't re-plan.
++        """
++    }
++
++    /// Builds Workflow Continuation Protocol section.
++    private static func buildWorkflowContinuationProtocol() -> String {
++        return """
++        ### Workflow Continuation (CRITICAL)
++
++        **The StatusSignalReminderInjector provides the status signal format - follow those instructions.**
++
++        **WITH TODO LIST:**
++        When user asks for multiple distinct outputs (e.g., "import X, analyze Y, create Z table"):
++        1. FIRST: Create a todo list with ALL requested deliverables
++        2. THEN: Execute each deliverable in sequence
++        3. AFTER EACH: Mark todo complete AND emit the appropriate status signal
++        4. FINALLY: Emit complete status only when ALL deliverables are provided
++
++        **WITHOUT TODO LIST (simple multi-step):**
++        For quick multi-step tasks that don't warrant a full todo list:
++        1. Execute step → emit continue status
++        2. When you receive the "continue" response from the system → Execute next step
++        3. Repeat until last step → emit complete status
++
++        **TODO MANAGEMENT - USING todo_operations TOOL:**
++
++        Create todos (write):
++        `todo_operations(operation="write", todoList=[{"id":1,"title":"Task 1","description":"...","status":"not-started"},...])`
++
++        Mark in-progress (update):
++        `todo_operations(operation="update", todoUpdates=[{"id":1,"status":"in-progress"}])`
++
++        **CRITICAL - Mark completed (update):**
++        `todo_operations(operation="update", todoUpdates=[{"id":1,"status":"completed"},{"id":2,"status":"in-progress"}])`
++
++        **You MUST call the update operation to mark tasks completed. The system cannot infer completion.**
++
++        **AFTER COMPLETING ANY TODO - MANDATORY SEQUENCE:**
++        1. You've done the work (e.g., brainstormed names)
++        2. IMMEDIATELY call: {"name":"todo_operations","arguments":{"operation":"update","todoUpdates":[{"id":CURRENT_ID,"status":"completed"},{"id":NEXT_ID,"status":"in-progress"}]}}
++        3. Then start the next task
++        4. Do NOT output the same work twice - if you've brainstormed, mark complete and move to research
++
++        **LOOP PREVENTION:**
++        When you receive the "continue" response from the system, DO THE NEXT THING - don't describe the last thing.
++        Red flags: describing same work multiple times, asking "should I continue?", same output appearing twice.
++
++        **Remember:** If user asks for N things, deliver N things. Partial = Failure.
++        """
++    }
++
+     /// Builds Workflow Mode execution behavior for complex multi-step workflows.
+     private static func buildWorkflowMode() -> String {
+         return """