Document public response file flow

[wwind123]

Summary

• Update the architecture flowchart to include public response files under /tmp/coding-review-agent-loop/responses.
• Update the sequence diagram so agent output flows through response files when supported, with parsed stdout as fallback.
• Clarify that logs are diagnostic and response files take precedence for Claude/Gemini GitHub comments.

Tests

• /home/wwind123/tools/coding-review-agent-loop/.venv/bin/python -m pytest tests/test_agent_loop.py -q

-- OpenAI Codex

[wwind123]

Review: Document public response file flow

The documentation changes accurately reflect the implementation introduced in base.py, claude.py, and gemini.py.

Flowchart — The new ResponseFiles node and its AgentCLIs → ResponseFiles → Orchestrator path correctly models what the code does: agents write to a per-UUID file under /tmp/coding-review-agent-loop/responses/<repo-slug>/<agent>/, and the orchestrator reads that file in preference to stdout.

Sequence diagram — The dual-arrow pattern (Agent-->>Resp + Agent-->>Orch: response file or parsed stdout) accurately captures the fallback logic in both backends: read_public_response_file(response_path) or text.

"if supported" qualifier on coder arrows — Correct. The coder can be configured as Claude (which does support response files), so the qualifier is appropriate rather than silently omitting those arrows.

Prose paragraph — "For Claude and Gemini, prompts also include a public response-file path… when that file exists and is non-empty, the loop posts the file contents to GitHub instead of stdout" is an accurate one-sentence summary of the read_public_response_file(response_path) or text pattern in both backends. The fact that Gemini also uses a stdout marker as an additional fallback is an implementation detail not necessary to expose here.

Test coverage — test_claude_public_response_file_is_used (lines ~569–) validates end-to-end that the response file contents reach the GitHub comment, and FakeRunner._maybe_write_public_response_file faithfully simulates the agent writing the file. Coverage is adequate.

No blocking issues found.

-- Anthropic Claude

[wwind123]

The documentation changes accurately reflect the implementation where agents write to public response files under /tmp/coding-review-agent-loop/responses/ to ensure clean GitHub comments.

Flowchart — The addition of the ResponseFiles node and its connections correctly models the data flow where agents produce public output that the orchestrator then consumes.

Sequence diagram — The updated arrows correctly show the dual-path logic: writing to a response file (if supported) and returning to the orchestrator with either the file content or parsed stdout. This matches the fallback implementation in both Claude and Gemini backends.

Prose clarification — The new paragraph at the end of the document provides a clear and accurate summary of why these files exist (to avoid leaking CLI diagnostics/tool narration) and where they are located.

I verified the paths in src/coding_review_agent_loop/agents/base.py and confirmed they match the documentation. Tests also pass.

-- Google Gemini