[Phase 2.5-F] Switch default engine to react and update documentation

[frankbria]

Summary

After CLI and API validation pass, switch the default engine from "plan" to "react" and update all relevant documentation.

Acceptance Criteria

• Default engine changed to `"react"` in `runtime.py`
• CLI help text updated to reflect new default
• `--engine plan` still available as fallback
• `CLAUDE.md` updated:
  • Agent system architecture section reflects ReAct loop
  • Execution flow diagram updated
  • New modules documented (react_agent.py, tools.py, editor.py)
  • --engine flag documented in commands section
• `docs/V2_STRATEGIC_ROADMAP.md` updated: Phase 2.5 marked complete
• `docs/AGENT_V3_UNIFIED_PLAN.md` status updated to "Implemented"
• All existing tests pass with react as default
• Smoke test: `cf work start --execute` (no --engine flag) uses ReactAgent

Dependencies

• Phase F validation: [Phase 2.5-F] End-to-end CLI validation with cf-test project #353, [Phase 2.5-F] Verify ReAct engine works via API routes #354 (both CLI and API validated)

Reference

• `docs/AGENT_V3_UNIFIED_PLAN.md`
• `CLAUDE.md` (project instructions)

[traycerai]

Plan

Observations

The codebase currently uses a plan-based agent architecture (file:codeframe/core/agent.py) without engine selection capability. Phase 2.5-F introduces a ReAct (Reasoning + Acting) loop architecture as an alternative execution engine. This ticket requires switching the default from "plan" to "react" after validation passes, while maintaining backward compatibility. The referenced modules (react_agent.py, tools.py, editor.py) and documentation (AGENT_V3_UNIFIED_PLAN.md) don't exist yet, indicating they're part of the Phase 2.5 implementation that precedes this ticket.

Approach

The implementation follows a configuration-first, documentation-second pattern. First, modify file:codeframe/core/runtime.py to change the default engine constant and add engine selection logic. Second, update file:codeframe/cli/app.py to expose the --engine flag with updated help text. Third, comprehensively update documentation files to reflect the new ReAct architecture, execution flow, and command usage. Finally, verify all existing tests pass with the new default. This approach ensures minimal code changes while maximizing documentation clarity for the architectural shift.

Implementation Steps

1. Update Default Engine Configuration

File: file:codeframe/core/runtime.py

Modify the execute_agent() function to:

• Add a DEFAULT_ENGINE constant at module level set to "react"
• Add an engine parameter to execute_agent() with default value DEFAULT_ENGINE
• Add conditional logic to select between plan-based agent (Agent class) and react-based agent (presumably ReactAgent class)
• Ensure the engine parameter is passed through from CLI and API layers

Key Changes:

# At module level (around line 20)
DEFAULT_ENGINE = "react"  # Changed from "plan"

# In execute_agent() signature (around line 591)
def execute_agent(
    workspace: Workspace,
    run: Run,
    dry_run: bool = False,
    debug: bool = False,
    verbose: bool = False,
    fix_coordinator: Optional["GlobalFixCoordinator"] = None,
    event_publisher: Optional["EventPublisher"] = None,
    engine: str = DEFAULT_ENGINE,  # NEW PARAMETER
) -> "AgentState":

Add engine selection logic before agent instantiation (around line 660):

• If engine == "react": instantiate ReactAgent
• If engine == "plan": instantiate Agent (existing)
• Else: raise ValueError for unsupported engine

2. Update CLI Command with --engine Flag

File: file:codeframe/cli/app.py

Modify the work_start() command (around line 1957):

Add new parameter:

engine: str = typer.Option(
    "react",
    "--engine",
    help="Execution engine: 'react' (default, ReAct loop) or 'plan' (legacy planner)",
)

Update the help text in the docstring to mention:

• Default engine is now "react" (ReAct loop architecture)
• Use --engine plan for legacy plan-based execution
• Example: cf work start <task-id> --execute --engine plan

Pass the engine parameter to runtime.execute_agent() call (around line 2048):

state = runtime.execute_agent(
    workspace, run, 
    dry_run=dry_run, 
    debug=debug, 
    verbose=verbose,
    engine=engine  # NEW
)

3. Update Batch Execution Commands

File: file:codeframe/cli/app.py

Locate batch execution commands (around line 2772) and add the same --engine flag to:

• work_batch_run() command
• Pass engine parameter through to the conductor/runtime layer

Ensure the engine selection is respected in parallel and serial execution modes.

4. Update CLAUDE.md Documentation

File: file:CLAUDE.md

Section: "Agent System Architecture" (around line 197)

Update the architecture table to include:

• ReactAgent | core/react_agent.py | ReAct loop orchestrator (observe-think-act cycle)
• Tools | core/tools.py | Tool definitions and execution for ReAct agent
• Editor | core/editor.py | File editing operations for ReAct agent

Update the "Execution Flow" section (around line 231) to show both architectures:

Plan-based Flow (legacy, --engine plan):

cf work start <id> --execute --engine plan
    │
    ├── runtime.start_task_run()
    └── runtime.execute_agent(engine="plan")
            │
            └── Agent.run(task_id)  # Existing planner-executor pattern

ReAct Flow (default, --engine react):

cf work start <id> --execute [--engine react]
    │
    ├── runtime.start_task_run()
    └── runtime.execute_agent(engine="react")
            │
            └── ReactAgent.run(task_id)
                ├── Observe: Load context, read files, check state
                ├── Think: Reason about next action using LLM
                ├── Act: Execute tool (edit file, run command, etc.)
                └── Loop until task complete or blocked

Add a new subsection "Engine Selection" explaining:

• Default is ReAct for better iterative problem-solving
• Plan-based engine available via --engine plan for compatibility
• ReAct uses tools.py for structured actions
• Editor.py provides file manipulation capabilities

Section: "Commands (v2 CLI)" (around line 261)

Update work execution examples:

# Work execution (single task)
cf work start <task-id> --execute          # Uses ReAct engine (default)
cf work start <task-id> --execute --engine plan  # Uses legacy planner
cf work start <task-id> --execute --engine react --verbose

5. Update V2_STRATEGIC_ROADMAP.md

File: file:docs/V2_STRATEGIC_ROADMAP.md

Add a new section after Phase 2 (around line 165):

## Phase 2.5: ReAct Agent Architecture ✅ COMPLETE

**Goal**: Implement ReAct (Reasoning + Acting) loop as the default execution engine.
**Status**: ✅ **COMPLETE** (2026-02-XX)

### Deliverables

1. **ReAct Agent Implementation** - ✅ COMPLETE
   - `core/react_agent.py` - Observe-Think-Act loop
   - `core/tools.py` - Structured tool definitions
   - `core/editor.py` - File editing operations
   
2. **CLI Validation** (#353) - ✅ COMPLETE
   - `--engine` flag added to work commands
   - Default switched to "react"
   - Legacy "plan" engine available as fallback

3. **API Validation** (#354) - ✅ COMPLETE
   - API endpoints support engine parameter
   - Backward compatibility maintained

4. **Documentation Update** (#355) - ✅ COMPLETE
   - CLAUDE.md reflects ReAct architecture
   - Execution flow diagrams updated
   - Command examples updated

### Architecture: ReAct Loop

The ReAct pattern provides better iterative problem-solving:
- **Observe**: Gather context, read files, check state
- **Think**: LLM reasons about next action
- **Act**: Execute tool (file edit, shell command, etc.)
- **Repeat**: Continue until task complete or blocked

### Success Criteria - ALL MET
- ✅ Default engine is "react"
- ✅ `--engine plan` fallback works
- ✅ All existing tests pass
- ✅ Smoke test: `cf work start <task-id> --execute` uses ReactAgent

Update the summary table (around line 317):

| Phase | Focus | Key Outcome | Status |
|-------|-------|-------------|--------|
| 1 | CLI Completion | Production-ready headless agent | ✅ **COMPLETE** |
| 2 | Server Layer | REST API + real-time events | ✅ **COMPLETE** |
| 2.5 | ReAct Architecture | Iterative agent execution | ✅ **COMPLETE** |
| 3 | Web UI | Modern dashboard | Planned |
| 4 | Multi-Agent | Agent swarms | Planned |
| 5 | Advanced | Power features | Planned |

6. Create AGENT_V3_UNIFIED_PLAN.md

File: file:docs/AGENT_V3_UNIFIED_PLAN.md (NEW)

Create a comprehensive document describing the ReAct architecture:

# Agent V3: Unified ReAct Architecture

**Status**: ✅ Implemented
**Default Engine**: react
**Legacy Engine**: plan (available via --engine plan)

## Overview

The V3 agent architecture uses the ReAct (Reasoning + Acting) pattern for iterative task execution. Unlike the plan-then-execute pattern, ReAct interleaves reasoning and action, allowing the agent to adapt based on intermediate results.

## Architecture Components

### ReactAgent (`core/react_agent.py`)
Main orchestrator implementing the observe-think-act loop.

**Key Methods**:
- `run(task_id)` - Main execution loop
- `_observe()` - Gather context and state
- `_think()` - LLM reasoning about next action
- `_act()` - Execute selected tool
- `_check_completion()` - Determine if task is done

### Tools (`core/tools.py`)
Structured tool definitions for agent actions.

**Available Tools**:
- `read_file` - Read file contents
- `edit_file` - Modify file with diff
- `create_file` - Create new file
- `run_command` - Execute shell command
- `search_codebase` - Search for patterns
- `verify_changes` - Run verification gates

### Editor (`core/editor.py`)
File manipulation operations with rollback support.

**Key Features**:
- Diff-based editing
- Syntax validation
- Rollback on error
- Multi-file transactions

## Execution Flow

```mermaid
sequenceDiagram
    participant CLI
    participant Runtime
    participant ReactAgent
    participant LLM
    participant Tools
    
    CLI->>Runtime: execute_agent(engine="react")
    Runtime->>ReactAgent: run(task_id)
    
    loop Until Complete or Blocked
        ReactAgent->>ReactAgent: observe()
        ReactAgent->>LLM: What should I do next?
        LLM->>ReactAgent: Use tool X with params Y
        ReactAgent->>Tools: execute(tool_name, params)
        Tools->>ReactAgent: result
        ReactAgent->>ReactAgent: check_completion()
    end
    
    ReactAgent->>Runtime: AgentState (COMPLETED/BLOCKED/FAILED)
    Runtime->>CLI: Final status

Comparison: Plan vs ReAct

Aspect	Plan Engine	ReAct Engine
Pattern	Plan all steps, then execute	Interleave reasoning and action
Adaptability	Fixed plan	Adapts based on results
Context	Loaded once	Re-evaluated each iteration
Error Handling	Retry entire plan	Adjust next action
Best For	Well-defined tasks	Exploratory tasks

Usage

Default (ReAct)

cf work start <task-id> --execute

Explicit ReAct

cf work start <task-id> --execute --engine react

Legacy Plan

cf work start <task-id> --execute --engine plan

Migration Notes

Existing tasks work with both engines. The ReAct engine is now default because:

1. Better handles unexpected errors
2. More efficient context usage
3. Adapts to changing requirements
4. Clearer reasoning trace

To use the legacy planner, add --engine plan to any work command.

### 7. Update API Layer

**File**: `file:codeframe/ui/routers/tasks_v2.py`

Add `engine` parameter to task execution endpoints:
- POST `/api/v2/tasks/{task_id}/execute`
- POST `/api/v2/batches/run`

Update request models to include optional `engine` field with default "react".

Ensure the engine parameter is passed through to `runtime.execute_agent()`.

### 8. Verification Steps

Run the following tests to ensure the switch is successful:

**Unit Tests**:
```bash
uv run pytest tests/core/test_agent.py -v
uv run pytest tests/core/test_runtime.py -v

Integration Tests:

uv run pytest tests/cli/test_v2_cli_integration.py -v
uv run pytest tests/integration/ -v

Smoke Test:

# Initialize test workspace
cf init /tmp/test-react --detect

# Create a simple task
cf tasks generate

# Execute with default (should use react)
cf work start <task-id> --execute --verbose

# Verify in output that ReactAgent is being used
# Look for "ReAct" or "observe-think-act" in logs

# Test fallback
cf work start <task-id> --execute --engine plan --verbose

9. Update OpenAPI Documentation

File: file:codeframe/ui/server.py

Update OpenAPI metadata to mention the engine parameter in relevant endpoints.

Add examples showing both engine: "react" and engine: "plan" in request bodies.

Visual Architecture

graph TD
    A[cf work start --execute] --> B{Engine Selection}
    B -->|Default: react| C[ReactAgent]
    B -->|--engine plan| D[Agent Legacy]
    
    C --> E[Observe-Think-Act Loop]
    E --> F[Tools.execute]
    F --> G[Editor.apply_changes]
    G --> E
    
    D --> H[Planner.create_plan]
    H --> I[Executor.run_steps]
    
    E --> J[AgentState]
    I --> J
    J --> K[Runtime.update_status]

Loading

Success Criteria Checklist

• DEFAULT_ENGINE = "react" in file:codeframe/core/runtime.py
• --engine flag added to cf work start command
• --engine flag added to cf work batch run command
• Help text updated to show "react" as default
• --engine plan works as fallback
• file:CLAUDE.md updated with ReAct architecture section
• file:CLAUDE.md execution flow diagram shows both engines
• file:CLAUDE.md documents react_agent.py, tools.py, editor.py
• file:CLAUDE.md commands section shows --engine examples
• file:docs/V2_STRATEGIC_ROADMAP.md has Phase 2.5 section marked complete
• file:docs/AGENT_V3_UNIFIED_PLAN.md created with full architecture
• API endpoints support engine parameter
• All existing tests pass: uv run pytest
• Smoke test passes: cf work start <task-id> --execute uses ReactAgent

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently uses a plan-based agent architecture (`file:codeframe/core/agent.py`) without engine selection capability. Phase 2.5-F introduces a ReAct (Reasoning + Acting) loop architecture as an alternative execution engine. This ticket requires switching the default from "plan" to "react" after validation passes, while maintaining backward compatibility. The referenced modules (`react_agent.py`, `tools.py`, `editor.py`) and documentation (`AGENT_V3_UNIFIED_PLAN.md`) don't exist yet, indicating they're part of the Phase 2.5 implementation that precedes this ticket.

## Approach

The implementation follows a configuration-first, documentation-second pattern. First, modify `file:codeframe/core/runtime.py` to change the default engine constant and add engine selection logic. Second, update `file:codeframe/cli/app.py` to expose the `--engine` flag with updated help text. Third, comprehensively update documentation files to reflect the new ReAct architecture, execution flow, and command usage. Finally, verify all existing tests pass with the new default. This approach ensures minimal code changes while maximizing documentation clarity for the architectural shift.

## Implementation Steps

### 1. Update Default Engine Configuration

**File**: `file:codeframe/core/runtime.py`

Modify the `execute_agent()` function to:
- Add a `DEFAULT_ENGINE` constant at module level set to `"react"`
- Add an `engine` parameter to `execute_agent()` with default value `DEFAULT_ENGINE`
- Add conditional logic to select between plan-based agent (`Agent` class) and react-based agent (presumably `ReactAgent` class)
- Ensure the engine parameter is passed through from CLI and API layers

**Key Changes**:
```python
# At module level (around line 20)
DEFAULT_ENGINE = "react"  # Changed from "plan"

# In execute_agent() signature (around line 591)
def execute_agent(
    workspace: Workspace,
    run: Run,
    dry_run: bool = False,
    debug: bool = False,
    verbose: bool = False,
    fix_coordinator: Optional["GlobalFixCoordinator"] = None,
    event_publisher: Optional["EventPublisher"] = None,
    engine: str = DEFAULT_ENGINE,  # NEW PARAMETER
) -> "AgentState":
```

Add engine selection logic before agent instantiation (around line 660):
- If `engine == "react"`: instantiate `ReactAgent` 
- If `engine == "plan"`: instantiate `Agent` (existing)
- Else: raise `ValueError` for unsupported engine

### 2. Update CLI Command with --engine Flag

**File**: `file:codeframe/cli/app.py`

Modify the `work_start()` command (around line 1957):

Add new parameter:
```python
engine: str = typer.Option(
    "react",
    "--engine",
    help="Execution engine: 'react' (default, ReAct loop) or 'plan' (legacy planner)",
)
```

Update the help text in the docstring to mention:
- Default engine is now "react" (ReAct loop architecture)
- Use `--engine plan` for legacy plan-based execution
- Example: `cf work start <task-id> --execute --engine plan`

Pass the engine parameter to `runtime.execute_agent()` call (around line 2048):
```python
state = runtime.execute_agent(
    workspace, run, 
    dry_run=dry_run, 
    debug=debug, 
    verbose=verbose,
    engine=engine  # NEW
)
```

### 3. Update Batch Execution Commands

**File**: `file:codeframe/cli/app.py`

Locate batch execution commands (around line 2772) and add the same `--engine` flag to:
- `work_batch_run()` command
- Pass engine parameter through to the conductor/runtime layer

Ensure the engine selection is respected in parallel and serial execution modes.

### 4. Update CLAUDE.md Documentation

**File**: `file:CLAUDE.md`

#### Section: "Agent System Architecture" (around line 197)

Update the architecture table to include:
- `ReactAgent` | `core/react_agent.py` | ReAct loop orchestrator (observe-think-act cycle)
- `Tools` | `core/tools.py` | Tool definitions and execution for ReAct agent
- `Editor` | `core/editor.py` | File editing operations for ReAct agent

Update the "Execution Flow" section (around line 231) to show both architectures:

**Plan-based Flow** (legacy, `--engine plan`):
```
cf work start <id> --execute --engine plan
    │
    ├── runtime.start_task_run()
    └── runtime.execute_agent(engine="plan")
            │
            └── Agent.run(task_id)  # Existing planner-executor pattern
```

**ReAct Flow** (default, `--engine react`):
```
cf work start <id> --execute [--engine react]
    │
    ├── runtime.start_task_run()
    └── runtime.execute_agent(engine="react")
            │
            └── ReactAgent.run(task_id)
                ├── Observe: Load context, read files, check state
                ├── Think: Reason about next action using LLM
                ├── Act: Execute tool (edit file, run command, etc.)
                └── Loop until task complete or blocked
```

Add a new subsection "Engine Selection" explaining:
- Default is ReAct for better iterative problem-solving
- Plan-based engine available via `--engine plan` for compatibility
- ReAct uses tools.py for structured actions
- Editor.py provides file manipulation capabilities

#### Section: "Commands (v2 CLI)" (around line 261)

Update work execution examples:
```bash
# Work execution (single task)
cf work start <task-id> --execute          # Uses ReAct engine (default)
cf work start <task-id> --execute --engine plan  # Uses legacy planner
cf work start <task-id> --execute --engine react --verbose
```

### 5. Update V2_STRATEGIC_ROADMAP.md

**File**: `file:docs/V2_STRATEGIC_ROADMAP.md`

Add a new section after Phase 2 (around line 165):

```markdown
## Phase 2.5: ReAct Agent Architecture ✅ COMPLETE

**Goal**: Implement ReAct (Reasoning + Acting) loop as the default execution engine.
**Status**: ✅ **COMPLETE** (2026-02-XX)

### Deliverables

1. **ReAct Agent Implementation** - ✅ COMPLETE
   - `core/react_agent.py` - Observe-Think-Act loop
   - `core/tools.py` - Structured tool definitions
   - `core/editor.py` - File editing operations
   
2. **CLI Validation** (#353) - ✅ COMPLETE
   - `--engine` flag added to work commands
   - Default switched to "react"
   - Legacy "plan" engine available as fallback

3. **API Validation** (#354) - ✅ COMPLETE
   - API endpoints support engine parameter
   - Backward compatibility maintained

4. **Documentation Update** (#355) - ✅ COMPLETE
   - CLAUDE.md reflects ReAct architecture
   - Execution flow diagrams updated
   - Command examples updated

### Architecture: ReAct Loop

The ReAct pattern provides better iterative problem-solving:
- **Observe**: Gather context, read files, check state
- **Think**: LLM reasons about next action
- **Act**: Execute tool (file edit, shell command, etc.)
- **Repeat**: Continue until task complete or blocked

### Success Criteria - ALL MET
- ✅ Default engine is "react"
- ✅ `--engine plan` fallback works
- ✅ All existing tests pass
- ✅ Smoke test: `cf work start <task-id> --execute` uses ReactAgent
```

Update the summary table (around line 317):
```markdown
| Phase | Focus | Key Outcome | Status |
|-------|-------|-------------|--------|
| 1 | CLI Completion | Production-ready headless agent | ✅ **COMPLETE** |
| 2 | Server Layer | REST API + real-time events | ✅ **COMPLETE** |
| 2.5 | ReAct Architecture | Iterative agent execution | ✅ **COMPLETE** |
| 3 | Web UI | Modern dashboard | Planned |
| 4 | Multi-Agent | Agent swarms | Planned |
| 5 | Advanced | Power features | Planned |
```

### 6. Create AGENT_V3_UNIFIED_PLAN.md

**File**: `file:docs/AGENT_V3_UNIFIED_PLAN.md` (NEW)

Create a comprehensive document describing the ReAct architecture:

```markdown
# Agent V3: Unified ReAct Architecture

**Status**: ✅ Implemented
**Default Engine**: react
**Legacy Engine**: plan (available via --engine plan)

## Overview

The V3 agent architecture uses the ReAct (Reasoning + Acting) pattern for iterative task execution. Unlike the plan-then-execute pattern, ReAct interleaves reasoning and action, allowing the agent to adapt based on intermediate results.

## Architecture Components

### ReactAgent (`core/react_agent.py`)
Main orchestrator implementing the observe-think-act loop.

**Key Methods**:
- `run(task_id)` - Main execution loop
- `_observe()` - Gather context and state
- `_think()` - LLM reasoning about next action
- `_act()` - Execute selected tool
- `_check_completion()` - Determine if task is done

### Tools (`core/tools.py`)
Structured tool definitions for agent actions.

**Available Tools**:
- `read_file` - Read file contents
- `edit_file` - Modify file with diff
- `create_file` - Create new file
- `run_command` - Execute shell command
- `search_codebase` - Search for patterns
- `verify_changes` - Run verification gates

### Editor (`core/editor.py`)
File manipulation operations with rollback support.

**Key Features**:
- Diff-based editing
- Syntax validation
- Rollback on error
- Multi-file transactions

## Execution Flow

```mermaid
sequenceDiagram
    participant CLI
    participant Runtime
    participant ReactAgent
    participant LLM
    participant Tools
    
    CLI->>Runtime: execute_agent(engine="react")
    Runtime->>ReactAgent: run(task_id)
    
    loop Until Complete or Blocked
        ReactAgent->>ReactAgent: observe()
        ReactAgent->>LLM: What should I do next?
        LLM->>ReactAgent: Use tool X with params Y
        ReactAgent->>Tools: execute(tool_name, params)
        Tools->>ReactAgent: result
        ReactAgent->>ReactAgent: check_completion()
    end
    
    ReactAgent->>Runtime: AgentState (COMPLETED/BLOCKED/FAILED)
    Runtime->>CLI: Final status
```

## Comparison: Plan vs ReAct

| Aspect | Plan Engine | ReAct Engine |
|--------|-------------|--------------|
| Pattern | Plan all steps, then execute | Interleave reasoning and action |
| Adaptability | Fixed plan | Adapts based on results |
| Context | Loaded once | Re-evaluated each iteration |
| Error Handling | Retry entire plan | Adjust next action |
| Best For | Well-defined tasks | Exploratory tasks |

## Usage

### Default (ReAct)
```bash
cf work start <task-id> --execute
```

### Explicit ReAct
```bash
cf work start <task-id> --execute --engine react
```

### Legacy Plan
```bash
cf work start <task-id> --execute --engine plan
```

## Migration Notes

Existing tasks work with both engines. The ReAct engine is now default because:
1. Better handles unexpected errors
2. More efficient context usage
3. Adapts to changing requirements
4. Clearer reasoning trace

To use the legacy planner, add `--engine plan` to any work command.
```

### 7. Update API Layer

**File**: `file:codeframe/ui/routers/tasks_v2.py`

Add `engine` parameter to task execution endpoints:
- POST `/api/v2/tasks/{task_id}/execute`
- POST `/api/v2/batches/run`

Update request models to include optional `engine` field with default "react".

Ensure the engine parameter is passed through to `runtime.execute_agent()`.

### 8. Verification Steps

Run the following tests to ensure the switch is successful:

**Unit Tests**:
```bash
uv run pytest tests/core/test_agent.py -v
uv run pytest tests/core/test_runtime.py -v
```

**Integration Tests**:
```bash
uv run pytest tests/cli/test_v2_cli_integration.py -v
uv run pytest tests/integration/ -v
```

**Smoke Test**:
```bash
# Initialize test workspace
cf init /tmp/test-react --detect

# Create a simple task
cf tasks generate

# Execute with default (should use react)
cf work start <task-id> --execute --verbose

# Verify in output that ReactAgent is being used
# Look for "ReAct" or "observe-think-act" in logs

# Test fallback
cf work start <task-id> --execute --engine plan --verbose
```

### 9. Update OpenAPI Documentation

**File**: `file:codeframe/ui/server.py`

Update OpenAPI metadata to mention the engine parameter in relevant endpoints.

Add examples showing both `engine: "react"` and `engine: "plan"` in request bodies.

## Visual Architecture

```mermaid
graph TD
    A[cf work start --execute] --> B{Engine Selection}
    B -->|Default: react| C[ReactAgent]
    B -->|--engine plan| D[Agent Legacy]
    
    C --> E[Observe-Think-Act Loop]
    E --> F[Tools.execute]
    F --> G[Editor.apply_changes]
    G --> E
    
    D --> H[Planner.create_plan]
    H --> I[Executor.run_steps]
    
    E --> J[AgentState]
    I --> J
    J --> K[Runtime.update_status]
```

## Success Criteria Checklist

- [ ] `DEFAULT_ENGINE = "react"` in `file:codeframe/core/runtime.py`
- [ ] `--engine` flag added to `cf work start` command
- [ ] `--engine` flag added to `cf work batch run` command
- [ ] Help text updated to show "react" as default
- [ ] `--engine plan` works as fallback
- [ ] `file:CLAUDE.md` updated with ReAct architecture section
- [ ] `file:CLAUDE.md` execution flow diagram shows both engines
- [ ] `file:CLAUDE.md` documents react_agent.py, tools.py, editor.py
- [ ] `file:CLAUDE.md` commands section shows --engine examples
- [ ] `file:docs/V2_STRATEGIC_ROADMAP.md` has Phase 2.5 section marked complete
- [ ] `file:docs/AGENT_V3_UNIFIED_PLAN.md` created with full architecture
- [ ] API endpoints support engine parameter
- [ ] All existing tests pass: `uv run pytest`
- [ ] Smoke test passes: `cf work start <task-id> --execute` uses ReactAgent

---

Execution Information

Branch: main
Commit: 99f0ea9

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#246 - feat(agents): trigger multi-agent execution after task approval [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!