fix: include pre-loaded file contents in ReactAgent system prompt

[frankbria]

Summary

• Surfaces already-loaded file contents in the ReactAgent system prompt, eliminating ~30% wasted iterations on redundant read_file calls
• Updates agent rules to acknowledge pre-loaded context, allowing immediate implementation
• Changes initial user message from "Start by reading relevant files" to a neutral prompt

What Changed

Area	Before	After
System prompt	Only file paths shown	File contents included via ## Relevant Source Files section
Base rules (line 64)	"ALWAYS read a file before editing it"	"Read files before editing unless already in Relevant Source Files"
Base rules (line 67)	"Never edit_file on a file you haven't read"	"...haven't seen (via read_file OR Relevant Source Files)"
Initial message	"Start by reading relevant files..."	"Relevant source files are provided above when available"

Root Cause

ContextLoader._load_file_contents() already loaded relevant files with token budgeting into context.loaded_files, but _build_system_prompt() never included them — only file paths from context.file_tree. Combined with rules mandating file reads, the agent wasted 7-9 iterations before its first write.

Expected Impact

• Agent starts writing by iteration 2-3 (instead of 10)
• Gains 7+ iterations for actual implementation
• Could complete 2-3 more files per task within the 30-iteration budget

Test Plan

• 4 new TDD tests in TestPreloadedFileContext class
• test_system_prompt_includes_loaded_files — verifies file contents appear in prompt
• test_system_prompt_no_loaded_files_section_when_empty — edge case: empty list
• test_rules_acknowledge_preloaded_context — old rule text removed
• test_initial_message_does_not_mandate_reading — no exploration mandate
• All 64 tests in test_react_agent.py pass
• All 1321 core tests pass
• Linting clean (ruff check)

Closes #373

Summary by CodeRabbit

• Improvements

  • Agent now surfaces pre-loaded source file contents in its planning prompt, improving context awareness.
  • Prompt guidance updated to acknowledge provided files and avoid forcing redundant file reads.
  • Better consistency in prompt layering and context composition for more efficient analysis.

• Tests

  • Added tests validating prompt output and messaging when files are preloaded vs. empty.

• Chore

  • Updated ignore rules to exclude a new test file.

[coderabbitai]

Walkthrough

The ReAct agent's system prompt now includes preloaded source file contents (from context.loaded_files) in Layer 2 and softens initial guidance to prefer using provided context and tools only if needed; tests were added/updated to validate this behavior.

Changes

Cohort / File(s)	Summary
Prompt Construction codeframe/core/react_agent.py	Embed a "Relevant Source Files" section (file paths + full contents) into the Layer 2 system prompt when context.loaded_files is present; soften base rules and the initial user instruction to reflect preloaded context and to use tools only as needed.
Test Coverage tests/core/test_react_agent.py	Import FileContent; update assertions that reference base rules and initial user message; add TestPreloadedFileContext covering inclusion/omission of loaded files and wording that acknowledges preloaded context.
Repository config .gitignore	Add ignore entry for tests/test_new_feature.py.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant ContextLoader
  participant ReactAgent
  participant LLM
  participant Tools
  User->>ReactAgent: Submit task + TaskContext
  ReactAgent->>ContextLoader: Request context (file_tree, loaded_files)
  ContextLoader-->>ReactAgent: Returns file tree + loaded_files
  ReactAgent->>LLM: Build system prompt (includes Relevant Source Files) and send prompt
  LLM-->>ReactAgent: Plan / actions
  ReactAgent->>Tools: Invoke only-if-needed (read_file / list_files / create_file)
  Tools-->>ReactAgent: Tool results
  ReactAgent-->>LLM: New observations / next actions

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: ReactAgent core loop with system prompt builder #361 — Prior changes to the ReactAgent system-prompt builder; closely related to adding/adjusting Layer 2 prompt content and rendering of preloaded files.

Poem

🐇 I hopped through trees and found a heap,
Of snippets, lines, where secrets sleep.
The prompt now shows them, neat and bright,
I nibble code and start at sight. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	❓ Inconclusive	The change to .gitignore adding 'tests/test_new_feature.py' appears unrelated to the PR objectives of surfacing pre-loaded file contents in the ReactAgent system prompt.	Clarify whether the .gitignore change is necessary for this PR or should be removed as an out-of-scope modification.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: including pre-loaded file contents in the ReactAgent system prompt, which is the primary objective of the PR.
Linked Issues check	✅ Passed	All coding requirements from issue #373 are met: (1) loaded file contents added to system prompt in 'Relevant Source Files' section [#373], (2) initial user message changed from mandate to neutral statement [#373], (3) system rules softened to acknowledge pre-loaded context [#373], and (4) tests verify these implementations [#373].
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/issue-373-preload-file-context

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

codeframe/core/react_agent.py (1)

529-537: Consider adding language hints to code blocks for better LLM comprehension.

The implementation correctly renders pre-loaded file contents. However, the code blocks lack language hints (e.g., ```python), which could help the LLM better understand the file type and syntax.

♻️ Proposed enhancement

 if context.loaded_files:
     file_lines = ["## Relevant Source Files"]
     for f in context.loaded_files:
         file_lines.append(f"### {f.path}")
-        file_lines.append("```")
+        # Infer language from file extension for syntax hints
+        ext = Path(f.path).suffix.lstrip(".")
+        lang_hint = {"py": "python", "js": "javascript", "ts": "typescript", "json": "json", "md": "markdown", "yaml": "yaml", "yml": "yaml"}.get(ext, "")
+        file_lines.append(f"```{lang_hint}")
         file_lines.append(f.content)
         file_lines.append("```")
         file_lines.append("")
     sections.append("\n".join(file_lines))

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Include pre-loaded file contents in ReactAgent._build_system_prompt and adjust ReactAgent.run message and Layer 1 rules to reference the Relevant Source Files section in react_agent.py

Update system prompt construction to embed TaskContext.loaded_files under ## Relevant Source Files, revise Layer 1 rules to allow editing files listed there, and change the initial user message to point to pre-provided sources. Add tests validating the prompt and message updates in test_react_agent.py.

📍Where to Start

Start with ReactAgent._build_system_prompt in react_agent.py.

---

Macroscope summarized 73eb480.

[claude]

Code Review - PR #379

Summary

This PR addresses a significant performance issue (issue #373) where the ReactAgent was wasting iterations on redundant file reads. The solution surfaces pre-loaded file contents from ContextLoader directly in the system prompt, reducing wasted iterations by ~30%.

✅ Strengths

1. Well-targeted optimization

• Addresses a real performance bottleneck (7-9 wasted iterations before first write)
• Makes excellent use of existing infrastructure (context.loaded_files was already populated but unused)
• Aligns with the core principle of efficiency within the 30-iteration budget

2. Clean implementation

• Changes are minimal and focused (18 additions, 5 deletions in core + comprehensive tests)
• The new "Relevant Source Files" section fits naturally into the existing 3-layer prompt structure
• Code formatting is clean with proper markdown structure

3. Excellent test coverage

• 4 new TDD tests in dedicated TestPreloadedFileContext class
• Tests cover positive case, edge case (empty list), rule verification, and initial message
• Tests verify both presence and absence of key strings appropriately

4. Consistent rule updates

• Base rules updated from prescriptive "ALWAYS read" to conditional "Read files before editing them unless...", which is more accurate
• Both rule statements (lines 64 and 68) updated consistently
• Initial message changed from directive to informative

🔍 Observations & Considerations

1. Potential token budget concerns
The implementation adds file contents directly to the system prompt without considering size:

# codeframe/core/react_agent.py:534-535
file_lines.append(f.content)  # No truncation or size check

While ContextLoader._load_file_contents() already has token budgeting logic (lines 479-503 in context.py), once files are loaded, their full contents are included. For large files or many files, this could:

• Consume significant context window early in Layer 2
• Leave less room for Layer 3 (task details, PRD, blockers)

Suggestion: Consider adding a sanity check or truncation for very large files in the prompt section (e.g., truncate individual files > 1000 lines with an ellipsis marker).

2. Code block language hint missing
The markdown code blocks don't specify a language:

file_lines.append("```")  # Line 533

This is fine for the LLM, but adding language hints (python, typescript, etc.) could improve syntax highlighting if prompts are ever logged/viewed. Not critical, but could be a future enhancement.

3. Test assertion could be more precise
In test_rules_acknowledge_preloaded_context, line 327:

assert "Relevant Source Files" in system_prompt

This verifies the section header exists, but doesn't verify the actual updated rule text. Consider also checking:

assert "unless their contents are already provided" in system_prompt
# or
assert "Read files before editing them unless" in system_prompt

This would more directly test that the rule was updated (not just that the section exists).

4. Documentation alignment
The PR references AGENT_V3_UNIFIED_PLAN.md in code comments (line 56), but the rules have diverged from "verbatim" as stated. Consider:

• Updating that comment to reflect rules are now conditional
• OR updating the source document to match the new rules

🐛 Potential Issues

None identified - The implementation is solid. The observations above are optimizations, not bugs.

🔒 Security

No security concerns. The change surfaces data that was already loaded and trusted.

⚡ Performance

Significant positive impact expected:

• Agent can start implementation at iteration 2-3 instead of 10
• Gains 7+ iterations for actual work
• Could complete 2-3 more file changes per task

The trade-off is slightly larger initial prompt, but this is acceptable given the iteration savings.

📋 Test Coverage

Excellent coverage:

• ✅ Positive case with multiple files
• ✅ Edge case (empty loaded_files)
• ✅ Rule text verification
• ✅ Initial message verification
• ✅ All 64 existing tests in test_react_agent.py remain valid (good regression prevention)

✅ Recommendation

Approve with minor suggestions. This is a well-implemented performance optimization that directly addresses a documented issue. The suggestions above are enhancements, not blockers.

Optional follow-ups:

1. Add file content size safety check (guard against extremely large files)
2. Improve test assertion in test_rules_acknowledge_preloaded_context to verify actual rule text
3. Update AGENT_V3_UNIFIED_PLAN.md or code comment about "verbatim" rules

Nice work on the clear PR description and thorough testing! 🎉

[claude]

Follow-up Review

I previously provided a comprehensive review of this PR. The code remains unchanged since that review.

Summary: This is a well-implemented performance optimization that addresses issue #373. The PR:

• ✅ Surfaces pre-loaded file contents in the system prompt (eliminating ~30% wasted iterations)
• ✅ Updates rules to acknowledge pre-loaded context
• ✅ Includes comprehensive test coverage (4 new tests)
• ✅ Maintains backward compatibility (all 64 existing tests pass)

My previous suggestions remain valid but are enhancements, not blockers:

1. Consider adding file content size safety checks for extremely large files
2. Could improve test assertion in test_rules_acknowledge_preloaded_context to verify actual rule text (not just section header)
3. Update comment on line 56 about "verbatim" rules since they're now conditional

Recommendation: Approve and merge. This is a solid improvement with clear benefits and no blocking issues.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.gitignore (1)

39-48: ⚠️ Potential issue | 🟠 Major

Avoid ignoring a concrete test file unless it is generated.

Adding tests/test_new_feature.py to .gitignore will keep that test out of version control and CI coverage, which is risky for a new feature. Unless this file is auto-generated, it should be tracked.

[claude]

Final Review - PR #379

✅ All Previous Feedback Addressed

The latest commit (73eb480) successfully addresses the suggestions from my initial review:

1. ✅ Test assertion improved - test_rules_acknowledge_preloaded_context now verifies the actual updated rule text ("Read files before editing them unless") rather than just checking for the section header
2. ✅ Documentation updated - Line 56 comment changed from "verbatim" to "adapted" to reflect that rules are now conditional on pre-loaded context

Code Quality Assessment

Architecture alignment: ✅ Excellent

• Follows the v2 core-first, CLI-first architecture
• Changes are confined to core module (no server/UI coupling)
• Leverages existing infrastructure (ContextLoader already did the work)

Implementation quality: ✅ Strong

• Minimal, focused changes (19 additions, 6 deletions in core)
• Clean integration into existing 3-layer prompt system
• Proper edge case handling (empty loaded_files list)

Test coverage: ✅ Comprehensive

• 4 dedicated tests in new TestPreloadedFileContext class
• Tests cover: file inclusion, empty edge case, rule updates, initial message
• All 64 existing tests continue to pass (good regression prevention)
• Test assertions are now precise and verify actual behavior

Performance impact: ✅ Significant improvement

• Eliminates 7-9 wasted iterations on redundant file reads (~30% savings)
• Gains 7+ iterations for actual implementation work
• Could enable 2-3 more file changes per task within the 30-iteration budget

Remaining Considerations

1. .gitignore change (out of scope)
The addition of tests/test_new_feature.py to .gitignore is unrelated to issue #373. Per the commit message (commit 43db9d8), this is due to TestWorkerAgent generating this file. This should ideally be in a separate PR, but it is a minor housekeeping item that does not affect functionality.

2. Token budget (future enhancement)
While ContextLoader has token budgeting logic, once files are loaded, their full contents are included in the prompt. For very large files (>1000 lines), this could consume significant context. Consider adding truncation in a future PR if this becomes an issue in practice.

Security & Best Practices

• ✅ No security concerns (only surfaces already-loaded, trusted data)
• ✅ Follows CLAUDE.md guidelines (core-first, no server dependencies)
• ✅ Consistent with codebase patterns
• ✅ Proper markdown formatting in generated prompt sections

Recommendation

✅ APPROVED - Ready to merge

This PR successfully resolves issue #373 with a clean, well-tested implementation. The performance improvement is substantial and the code quality is high. All previous review feedback has been addressed.

Impact: High-value optimization that directly improves agent efficiency within the iteration budget, a core concern for the v2 architecture.

Nice work! 🎉