[Phase 2.5-C] Implement ReactAgent core loop with system prompt builder

[frankbria]

Summary

Create codeframe/core/react_agent.py — the core ReAct loop agent that replaces Plan-and-Execute for code generation. This is the central module of the Phase 2.5 redesign.

Acceptance Criteria

• ReactAgent class in codeframe/core/react_agent.py:
  • run(task_id: str) -> AgentState — main entry point
  • ReAct loop: LLM call with tools → execute tool calls → append results → repeat
  • Max 30 iterations hard cap
  • Termination: text-only response (no tool calls) = agent thinks it's done
  • Temperature 0.0 for deterministic execution
• System prompt builder with 3-layer structure:
  • Layer 1 (Base): Agent identity, tool descriptions (auto-generated from schemas), core rules, code quality constraints, termination conditions, decision-making autonomy
  • Layer 2 (Project): AGENTS.md/CLAUDE.md content (from agents_config.py), tech stack, file tree summary
  • Layer 3 (Task): Task title/description, PRD content (truncated to 5K), answered blockers
• Conversation management: builds proper Anthropic API message format with tool_calls and tool_results
• Intent preview: for HIGH complexity or greenfield tasks, system prompt instructs agent to outline approach before coding
• Uses adapters/llm/base.py types: Tool, ToolCall, ToolResult
• Delegates tool execution to tools.py:execute_tool()
• Final verification: when agent stops calling tools, run all gates (ruff + pytest)
• If final verification fails: re-enter loop for up to 5 more iterations with error context
• Tests in tests/core/test_react_agent.py:
  • Loop terminates on text-only response
  • Loop terminates at max iterations
  • Tool calls dispatched correctly
  • System prompt contains all 3 layers
  • Final verification triggered on completion
  • Uses mock LLM provider for unit tests
• All existing tests pass

Implementation Notes

• The existing Agent class in agent.py is NOT modified — ReactAgent is a parallel implementation
• Use MockLLMProvider from adapters/llm/mock.py for testing
• Verify that the Anthropic adapter can handle multi-turn tool-use conversations (may need minor update to anthropic.py)
• The system prompt rules from docs/AGENT_V3_UNIFIED_PLAN.md "Base Prompt (Layer 1)" section should be used verbatim
• context.py:ContextLoader is reused for initial context loading

Dependencies

• Phase A: [Phase 2.5-A] Implement SearchReplaceEditor with fuzzy matching #343 (editor.py)
• Phase B: [Phase 2.5-B] Implement read-only agent tools (read_file, list_files, search_codebase) #344, [Phase 2.5-B] Implement write agent tools (edit_file, create_file) #345, [Phase 2.5-B] Implement execution agent tools (run_command, run_tests) #346 (all tools must exist)

Subsumed Issues

• Cross-file naming inconsistency (task feat(sprint-4): Multi-Agent Coordination System - P0 & P1 Complete #3) — ReAct loop reads files before writing, preventing this structurally
• Dependency drift (task Brainstorming: Integrate remaining general concepts into specification #2) — search-replace editing only changes targeted text
• Verification retry early exit (task feat: Project schema refactoring with API endpoint integration #5) — ReAct loop IS the self-correction loop

Reference

• docs/AGENT_V3_UNIFIED_PLAN.md (Architecture, System Prompt Design)
• docs/REACT_AGENT_ARCHITECTURE.md (Section 2, 6)
• docs/AGENT_ARCHITECTURE_CRITIQUE.md (Section 2.2 — hybrid approach)

[traycerai]

Plan

Observations

The codebase currently implements a Plan-and-Execute architecture where the Agent class in file:codeframe/core/agent.py uses a Planner to create an implementation plan upfront, then executes steps sequentially. Phase 2.5-C introduces a fundamental architectural shift to a ReAct (Reasoning + Acting) loop pattern where the LLM iteratively decides which tools to call based on the current state. The existing LLM adapter infrastructure in file:codeframe/adapters/llm/base.py already supports tool use with Tool, ToolCall, and ToolResult types, and the AnthropicProvider in file:codeframe/adapters/llm/anthropic.py handles multi-turn tool conversations. The ContextLoader in file:codeframe/core/context.py provides task context loading, and AgentPreferences from file:codeframe/core/agents_config.py loads AGENTS.md/CLAUDE.md content. The verification gates in file:codeframe/core/gates.py provide ruff and pytest checking capabilities.

Approach

Implement a parallel ReactAgent class that coexists with the existing Agent without modifying it. The ReactAgent will use a ReAct loop architecture where the LLM is given tools and makes iterative decisions about which tools to call. The implementation follows a three-layer system prompt structure: (1) Base layer with agent identity and tool schemas, (2) Project layer with AGENTS.md content and file tree, (3) Task layer with PRD and blockers. The agent runs for up to 30 iterations, terminating when the LLM returns a text-only response (no tool calls). After termination, final verification runs all gates, and if verification fails, the agent re-enters the loop for up to 5 more iterations with error context. Tool execution will be delegated to a new tools.py module with an execute_tool() function that dispatches to individual tool implementations. The implementation uses the existing MockProvider for testing and ensures all existing tests continue to pass.

Implementation Steps

1. Create Tool Infrastructure (Phase B Dependencies)

File: file:codeframe/core/tools.py

Create the tool execution dispatcher and tool schema definitions:

• Define tool schemas as Tool objects (from file:codeframe/adapters/llm/base.py) for each tool:

  • read_file - Read file contents with path parameter
  • write_file - Write/create file with path and content parameters
  • edit_file - Search-replace editing (depends on editor.py from [Phase 2.5-A] Implement SearchReplaceEditor with fuzzy matching #343)
  • list_files - List directory contents with optional pattern
  • run_command - Execute shell commands (safe subset only)
  • search_code - Search codebase for patterns

• Implement execute_tool(tool_call: ToolCall, workspace: Workspace) -> ToolResult:

  • Dispatch based on tool_call.name to individual tool handlers
  • Validate inputs against tool schemas
  • Execute the tool operation
  • Return ToolResult with success/error status
  • Handle exceptions and convert to error results

• Implement individual tool handler functions:

  • _execute_read_file(input: dict, workspace: Workspace) -> str
  • _execute_write_file(input: dict, workspace: Workspace) -> str
  • _execute_edit_file(input: dict, workspace: Workspace) -> str (uses editor from [Phase 2.5-A] Implement SearchReplaceEditor with fuzzy matching #343)
  • _execute_list_files(input: dict, workspace: Workspace) -> str
  • _execute_run_command(input: dict, workspace: Workspace) -> str
  • _execute_search_code(input: dict, workspace: Workspace) -> str

• Add safety validations:

  • Path traversal prevention (no .. in paths)
  • Command whitelist for run_command
  • File size limits for read operations

File: file:codeframe/core/editor.py (from Phase A #343)

Implement search-replace file editing:

• apply_edit(file_path: Path, search: str, replace: str) -> EditResult:

  • Read file content
  • Find exact match for search string
  • Replace with new content
  • Write back to file
  • Return success/failure with details

• Handle edge cases:

  • Multiple matches (fail with error)
  • No matches (fail with error)
  • File doesn't exist (fail with error)

2. Create ReactAgent Core Loop

File: file:codeframe/core/react_agent.py

Implement the main ReactAgent class:

• Class Definition:

  class ReactAgent:
      def __init__(
          self,
          workspace: Workspace,
          llm_provider: LLMProvider,
          max_iterations: int = 30,
          max_verification_retries: int = 5,
      )

• Main Entry Point - run(task_id: str) -> AgentState:

  • Load task context using ContextLoader from file:codeframe/core/context.py
  • Build 3-layer system prompt using _build_system_prompt()
  • Initialize conversation history (empty messages list)
  • Enter ReAct loop via _react_loop()
  • Run final verification via _run_final_verification()
  • Return final AgentState (COMPLETED, FAILED, or BLOCKED)

• ReAct Loop - _react_loop(context: TaskContext, system_prompt: str) -> AgentState:

  • Initialize iteration counter
  • While iteration < max_iterations:
    • Call LLM with llm_provider.complete(messages, tools=TOOL_SCHEMAS, temperature=0.0, system=system_prompt)
    • If response has no tool calls: return COMPLETED (agent thinks it's done)
    • For each tool call in response:
      • Execute tool via execute_tool() from file:codeframe/core/tools.py
      • Collect ToolResult objects
    • Append assistant message with tool calls to conversation
    • Append user message with tool results to conversation
    • Increment iteration counter
  • If max iterations reached: return FAILED with "max iterations" reason

• System Prompt Builder - _build_system_prompt(context: TaskContext) -> str:

  • Layer 1 (Base):
    • Agent identity and role
    • Tool descriptions (auto-generated from tool schemas)
    • Core rules: "You are an autonomous coding agent. Use tools to complete the task. When done, respond with text only (no tool calls)."
    • Code quality constraints: "Follow existing patterns, write tests, use type hints"
    • Termination conditions: "Stop calling tools when task is complete"
    • Decision-making autonomy: "Make tactical decisions without asking"
  • Layer 2 (Project):
    • AGENTS.md/CLAUDE.md content from context.preferences.raw_content
    • Tech stack from context.tech_stack
    • File tree summary (first 100 files, grouped by directory)
  • Layer 3 (Task):
    • Task title and description
    • PRD content (truncated to 5K chars if longer)
    • Answered blockers from context.answered_blockers
  • For HIGH complexity or greenfield tasks: add intent preview instruction

• Final Verification - _run_final_verification(context: TaskContext) -> tuple[bool, Optional[str]]:

  • Run all gates via gates.run(workspace) from file:codeframe/core/gates.py
  • If passed: return (True, None)
  • If failed:
    • For retry_attempt in range(max_verification_retries):
      • Build error context from gate results
      • Append error message to conversation
      • Re-enter _react_loop() with error context
      • Re-run gates
      • If passed: return (True, None)
    • Return (False, error_summary)

• Conversation Management - _build_messages(history: list[Message]) -> list[dict]:

  • Convert Message objects to Anthropic API format
  • Handle tool_calls and tool_results properly
  • Use Message.to_dict() from file:codeframe/adapters/llm/base.py

• Intent Preview (for HIGH complexity tasks):

  • Add to system prompt: "Before coding, outline your approach in 3-5 bullet points"
  • First LLM response should be text-only with approach
  • Then proceed with tool calls

3. Create Test Suite

File: file:tests/core/test_react_agent.py

Implement comprehensive unit tests:

• Test Loop Termination on Text Response:

  • Mock LLM to return text-only response
  • Verify agent returns COMPLETED
  • Verify no tool calls executed

• Test Loop Termination at Max Iterations:

  • Mock LLM to always return tool calls
  • Verify agent stops at 30 iterations
  • Verify returns FAILED with "max iterations" message

• Test Tool Call Dispatch:

  • Mock LLM to return tool calls
  • Verify execute_tool() called with correct parameters
  • Verify tool results appended to conversation

• Test System Prompt Contains All 3 Layers:

  • Create task context with PRD, preferences, tech stack
  • Build system prompt
  • Assert contains base layer rules
  • Assert contains AGENTS.md content
  • Assert contains task description and PRD

• Test Final Verification Triggered:

  • Mock LLM to complete task
  • Mock gates to pass
  • Verify gates.run() called
  • Verify agent returns COMPLETED

• Test Verification Retry on Failure:

  • Mock LLM to complete task
  • Mock gates to fail first time, pass second time
  • Verify agent re-enters loop with error context
  • Verify agent returns COMPLETED after retry

• Test Verification Retry Exhaustion:

  • Mock gates to always fail
  • Verify agent stops after 5 retries
  • Verify returns FAILED with gate errors

• Test Intent Preview for HIGH Complexity:

  • Create HIGH complexity task
  • Verify system prompt includes intent preview instruction
  • Mock LLM to return approach outline first
  • Verify conversation flow

• Use MockProvider:

  • All tests use MockProvider from file:codeframe/adapters/llm/mock.py
  • Configure canned responses via add_response() and add_tool_response()
  • Verify call tracking via provider.calls

4. Integration Points

Update file:codeframe/core/runtime.py (optional, for future integration):

• Add use_react_agent: bool = False parameter to execute_agent()
• If use_react_agent=True: instantiate ReactAgent instead of Agent
• Keep existing Agent as default for backward compatibility

Update file:codeframe/cli/app.py (optional, for future CLI flag):

• Add --react flag to cf work start command
• Pass flag to runtime.execute_agent(use_react_agent=True)

5. Documentation

Create file:docs/REACT_AGENT_ARCHITECTURE.md:

• Document ReAct loop architecture
• Explain 3-layer system prompt design
• Describe tool execution flow
• Include sequence diagram of agent loop
• Document termination conditions
• Explain verification retry mechanism

Update file:CLAUDE.md:

• Add ReactAgent to agent system components table
• Document --react flag (when implemented)
• Note that ReactAgent is experimental/parallel implementation

6. Validation

• Run all existing tests: uv run pytest - ensure no regressions
• Run new ReactAgent tests: uv run pytest tests/core/test_react_agent.py -v
• Verify test coverage: uv run pytest --cov=codeframe.core.react_agent
• Manual testing with simple task using MockProvider
• Verify system prompt generation with real task context
• Verify tool execution with safe operations (read_file, list_files)

Architecture Diagram

sequenceDiagram
    participant CLI as CLI/Runtime
    participant RA as ReactAgent
    participant LLM as LLM Provider
    participant Tools as execute_tool()
    participant Gates as Verification Gates

    CLI->>RA: run(task_id)
    RA->>RA: Load context (PRD, files, blockers)
    RA->>RA: Build 3-layer system prompt
    
    loop ReAct Loop (max 30 iterations)
        RA->>LLM: complete(messages, tools, system_prompt)
        LLM-->>RA: Response (text + tool_calls)
        
        alt Has tool calls
            loop For each tool call
                RA->>Tools: execute_tool(tool_call)
                Tools-->>RA: ToolResult
            end
            RA->>RA: Append messages to conversation
        else Text only (no tools)
            RA->>RA: Break loop (agent done)
        end
    end
    
    RA->>Gates: run(workspace)
    Gates-->>RA: GateResult
    
    alt Gates failed
        loop Retry (max 5 times)
            RA->>RA: Add error context to conversation
            RA->>LLM: Re-enter ReAct loop
            RA->>Gates: run(workspace)
            alt Gates passed
                RA->>RA: Break retry loop
            end
        end
    end
    
    RA-->>CLI: AgentState (COMPLETED/FAILED/BLOCKED)

Loading

Key Design Decisions

1. Parallel Implementation: ReactAgent coexists with existing Agent to avoid breaking changes
2. Tool Schema First: Define tool schemas before implementation to guide LLM behavior
3. Temperature 0.0: Deterministic execution for reproducibility
4. 3-Layer Prompt: Separates concerns (base rules, project context, task specifics)
5. Text-Only Termination: Agent signals completion by not calling tools
6. Verification Retry: Gives agent multiple chances to fix gate failures
7. MockProvider Testing: All tests use mock to avoid API costs and ensure determinism

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently implements a Plan-and-Execute architecture where the `Agent` class in `file:codeframe/core/agent.py` uses a `Planner` to create an implementation plan upfront, then executes steps sequentially. Phase 2.5-C introduces a fundamental architectural shift to a ReAct (Reasoning + Acting) loop pattern where the LLM iteratively decides which tools to call based on the current state. The existing LLM adapter infrastructure in `file:codeframe/adapters/llm/base.py` already supports tool use with `Tool`, `ToolCall`, and `ToolResult` types, and the `AnthropicProvider` in `file:codeframe/adapters/llm/anthropic.py` handles multi-turn tool conversations. The `ContextLoader` in `file:codeframe/core/context.py` provides task context loading, and `AgentPreferences` from `file:codeframe/core/agents_config.py` loads AGENTS.md/CLAUDE.md content. The verification gates in `file:codeframe/core/gates.py` provide ruff and pytest checking capabilities.

## Approach

Implement a parallel `ReactAgent` class that coexists with the existing `Agent` without modifying it. The ReactAgent will use a ReAct loop architecture where the LLM is given tools and makes iterative decisions about which tools to call. The implementation follows a three-layer system prompt structure: (1) Base layer with agent identity and tool schemas, (2) Project layer with AGENTS.md content and file tree, (3) Task layer with PRD and blockers. The agent runs for up to 30 iterations, terminating when the LLM returns a text-only response (no tool calls). After termination, final verification runs all gates, and if verification fails, the agent re-enters the loop for up to 5 more iterations with error context. Tool execution will be delegated to a new `tools.py` module with an `execute_tool()` function that dispatches to individual tool implementations. The implementation uses the existing `MockProvider` for testing and ensures all existing tests continue to pass.

## Implementation Steps

### 1. Create Tool Infrastructure (Phase B Dependencies)

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

Create the tool execution dispatcher and tool schema definitions:

- Define tool schemas as `Tool` objects (from `file:codeframe/adapters/llm/base.py`) for each tool:
  - `read_file` - Read file contents with path parameter
  - `write_file` - Write/create file with path and content parameters  
  - `edit_file` - Search-replace editing (depends on editor.py from #343)
  - `list_files` - List directory contents with optional pattern
  - `run_command` - Execute shell commands (safe subset only)
  - `search_code` - Search codebase for patterns

- Implement `execute_tool(tool_call: ToolCall, workspace: Workspace) -> ToolResult`:
  - Dispatch based on `tool_call.name` to individual tool handlers
  - Validate inputs against tool schemas
  - Execute the tool operation
  - Return `ToolResult` with success/error status
  - Handle exceptions and convert to error results

- Implement individual tool handler functions:
  - `_execute_read_file(input: dict, workspace: Workspace) -> str`
  - `_execute_write_file(input: dict, workspace: Workspace) -> str`
  - `_execute_edit_file(input: dict, workspace: Workspace) -> str` (uses editor from #343)
  - `_execute_list_files(input: dict, workspace: Workspace) -> str`
  - `_execute_run_command(input: dict, workspace: Workspace) -> str`
  - `_execute_search_code(input: dict, workspace: Workspace) -> str`

- Add safety validations:
  - Path traversal prevention (no `..` in paths)
  - Command whitelist for `run_command`
  - File size limits for read operations

**File: `file:codeframe/core/editor.py`** (from Phase A #343)

Implement search-replace file editing:

- `apply_edit(file_path: Path, search: str, replace: str) -> EditResult`:
  - Read file content
  - Find exact match for search string
  - Replace with new content
  - Write back to file
  - Return success/failure with details

- Handle edge cases:
  - Multiple matches (fail with error)
  - No matches (fail with error)
  - File doesn't exist (fail with error)

### 2. Create ReactAgent Core Loop

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

Implement the main ReactAgent class:

- **Class Definition**:
  ```python
  class ReactAgent:
      def __init__(
          self,
          workspace: Workspace,
          llm_provider: LLMProvider,
          max_iterations: int = 30,
          max_verification_retries: int = 5,
      )
  ```

- **Main Entry Point** - `run(task_id: str) -> AgentState`:
  - Load task context using `ContextLoader` from `file:codeframe/core/context.py`
  - Build 3-layer system prompt using `_build_system_prompt()`
  - Initialize conversation history (empty messages list)
  - Enter ReAct loop via `_react_loop()`
  - Run final verification via `_run_final_verification()`
  - Return final `AgentState` (COMPLETED, FAILED, or BLOCKED)

- **ReAct Loop** - `_react_loop(context: TaskContext, system_prompt: str) -> AgentState`:
  - Initialize iteration counter
  - While iteration < max_iterations:
    - Call LLM with `llm_provider.complete(messages, tools=TOOL_SCHEMAS, temperature=0.0, system=system_prompt)`
    - If response has no tool calls: return COMPLETED (agent thinks it's done)
    - For each tool call in response:
      - Execute tool via `execute_tool()` from `file:codeframe/core/tools.py`
      - Collect `ToolResult` objects
    - Append assistant message with tool calls to conversation
    - Append user message with tool results to conversation
    - Increment iteration counter
  - If max iterations reached: return FAILED with "max iterations" reason

- **System Prompt Builder** - `_build_system_prompt(context: TaskContext) -> str`:
  - **Layer 1 (Base)**: 
    - Agent identity and role
    - Tool descriptions (auto-generated from tool schemas)
    - Core rules: "You are an autonomous coding agent. Use tools to complete the task. When done, respond with text only (no tool calls)."
    - Code quality constraints: "Follow existing patterns, write tests, use type hints"
    - Termination conditions: "Stop calling tools when task is complete"
    - Decision-making autonomy: "Make tactical decisions without asking"
  - **Layer 2 (Project)**:
    - AGENTS.md/CLAUDE.md content from `context.preferences.raw_content`
    - Tech stack from `context.tech_stack`
    - File tree summary (first 100 files, grouped by directory)
  - **Layer 3 (Task)**:
    - Task title and description
    - PRD content (truncated to 5K chars if longer)
    - Answered blockers from `context.answered_blockers`
  - For HIGH complexity or greenfield tasks: add intent preview instruction

- **Final Verification** - `_run_final_verification(context: TaskContext) -> tuple[bool, Optional[str]]`:
  - Run all gates via `gates.run(workspace)` from `file:codeframe/core/gates.py`
  - If passed: return (True, None)
  - If failed:
    - For retry_attempt in range(max_verification_retries):
      - Build error context from gate results
      - Append error message to conversation
      - Re-enter `_react_loop()` with error context
      - Re-run gates
      - If passed: return (True, None)
    - Return (False, error_summary)

- **Conversation Management** - `_build_messages(history: list[Message]) -> list[dict]`:
  - Convert `Message` objects to Anthropic API format
  - Handle tool_calls and tool_results properly
  - Use `Message.to_dict()` from `file:codeframe/adapters/llm/base.py`

- **Intent Preview** (for HIGH complexity tasks):
  - Add to system prompt: "Before coding, outline your approach in 3-5 bullet points"
  - First LLM response should be text-only with approach
  - Then proceed with tool calls

### 3. Create Test Suite

**File: `file:tests/core/test_react_agent.py`**

Implement comprehensive unit tests:

- **Test Loop Termination on Text Response**:
  - Mock LLM to return text-only response
  - Verify agent returns COMPLETED
  - Verify no tool calls executed

- **Test Loop Termination at Max Iterations**:
  - Mock LLM to always return tool calls
  - Verify agent stops at 30 iterations
  - Verify returns FAILED with "max iterations" message

- **Test Tool Call Dispatch**:
  - Mock LLM to return tool calls
  - Verify `execute_tool()` called with correct parameters
  - Verify tool results appended to conversation

- **Test System Prompt Contains All 3 Layers**:
  - Create task context with PRD, preferences, tech stack
  - Build system prompt
  - Assert contains base layer rules
  - Assert contains AGENTS.md content
  - Assert contains task description and PRD

- **Test Final Verification Triggered**:
  - Mock LLM to complete task
  - Mock gates to pass
  - Verify `gates.run()` called
  - Verify agent returns COMPLETED

- **Test Verification Retry on Failure**:
  - Mock LLM to complete task
  - Mock gates to fail first time, pass second time
  - Verify agent re-enters loop with error context
  - Verify agent returns COMPLETED after retry

- **Test Verification Retry Exhaustion**:
  - Mock gates to always fail
  - Verify agent stops after 5 retries
  - Verify returns FAILED with gate errors

- **Test Intent Preview for HIGH Complexity**:
  - Create HIGH complexity task
  - Verify system prompt includes intent preview instruction
  - Mock LLM to return approach outline first
  - Verify conversation flow

- **Use MockProvider**:
  - All tests use `MockProvider` from `file:codeframe/adapters/llm/mock.py`
  - Configure canned responses via `add_response()` and `add_tool_response()`
  - Verify call tracking via `provider.calls`

### 4. Integration Points

**Update `file:codeframe/core/runtime.py`** (optional, for future integration):

- Add `use_react_agent: bool = False` parameter to `execute_agent()`
- If `use_react_agent=True`: instantiate `ReactAgent` instead of `Agent`
- Keep existing `Agent` as default for backward compatibility

**Update `file:codeframe/cli/app.py`** (optional, for future CLI flag):

- Add `--react` flag to `cf work start` command
- Pass flag to `runtime.execute_agent(use_react_agent=True)`

### 5. Documentation

**Create `file:docs/REACT_AGENT_ARCHITECTURE.md`**:

- Document ReAct loop architecture
- Explain 3-layer system prompt design
- Describe tool execution flow
- Include sequence diagram of agent loop
- Document termination conditions
- Explain verification retry mechanism

**Update `file:CLAUDE.md`**:

- Add ReactAgent to agent system components table
- Document `--react` flag (when implemented)
- Note that ReactAgent is experimental/parallel implementation

### 6. Validation

- Run all existing tests: `uv run pytest` - ensure no regressions
- Run new ReactAgent tests: `uv run pytest tests/core/test_react_agent.py -v`
- Verify test coverage: `uv run pytest --cov=codeframe.core.react_agent`
- Manual testing with simple task using `MockProvider`
- Verify system prompt generation with real task context
- Verify tool execution with safe operations (read_file, list_files)

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI/Runtime
    participant RA as ReactAgent
    participant LLM as LLM Provider
    participant Tools as execute_tool()
    participant Gates as Verification Gates

    CLI->>RA: run(task_id)
    RA->>RA: Load context (PRD, files, blockers)
    RA->>RA: Build 3-layer system prompt
    
    loop ReAct Loop (max 30 iterations)
        RA->>LLM: complete(messages, tools, system_prompt)
        LLM-->>RA: Response (text + tool_calls)
        
        alt Has tool calls
            loop For each tool call
                RA->>Tools: execute_tool(tool_call)
                Tools-->>RA: ToolResult
            end
            RA->>RA: Append messages to conversation
        else Text only (no tools)
            RA->>RA: Break loop (agent done)
        end
    end
    
    RA->>Gates: run(workspace)
    Gates-->>RA: GateResult
    
    alt Gates failed
        loop Retry (max 5 times)
            RA->>RA: Add error context to conversation
            RA->>LLM: Re-enter ReAct loop
            RA->>Gates: run(workspace)
            alt Gates passed
                RA->>RA: Break retry loop
            end
        end
    end
    
    RA-->>CLI: AgentState (COMPLETED/FAILED/BLOCKED)
```

## Key Design Decisions

1. **Parallel Implementation**: ReactAgent coexists with existing Agent to avoid breaking changes
2. **Tool Schema First**: Define tool schemas before implementation to guide LLM behavior
3. **Temperature 0.0**: Deterministic execution for reproducibility
4. **3-Layer Prompt**: Separates concerns (base rules, project context, task specifics)
5. **Text-Only Termination**: Agent signals completion by not calling tools
6. **Verification Retry**: Gives agent multiple chances to fix gate failures
7. **MockProvider Testing**: All tests use mock to avoid API costs and ensure determinism

---

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

#10 - feat(frontend): Multi-Agent State Management with React Context [merged]
#11 - feat: Convert worker agents to async/await pattern (cf-48) [merged]
#125 - Implement WorkerAgent execute_task method [merged]
#129 - Implement Project.start() with LeadAgent integration [merged]
#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!