Feature request: richer review context — auto-include AGENTS.md + spec↔file mapping

[qiankunli]

Context: we've integrated ocr into "devloop"

devloop is an agent plugin (Claude Code today) for an aggregate-workspace dev loop — a state bus + hard guards that drive enter → develop → commit/MR → human merge. We've wired ocr in as a lifecycle hook: when an MR is created, a background

ocr review --from origin/<target> --to HEAD --format json --repo <repo>

runs (fire-and-forget, doesn't block commit), and we post the result as an MR comment (so each MR accumulates a review history) plus surface it back to the agent session. ocr keeps its own LLM config; this has worked really well — thank you for the tool. 🙏

We're now focused on review accuracy, and the main lever is giving ocr more context. We already auto-pass --background (commit messages + MR title/description). Two further context sources would help a lot but need ocr-side support:

---

1. Auto-include the repo's AGENTS.md as review context

Many repos keep their conventions / architecture in an AGENTS.md (commonly at the repo root, or server/AGENTS.md / backend/AGENTS.md). These are exactly the "house rules" a reviewer must know: layering boundaries, mandatory timeouts/connection-pool config, SQL-dialect portability, naming, etc.

Request: if ocr detects an AGENTS.md in the repo (or the resolved code dir), automatically include its content as review context (alongside --background / rules), ideally with a sensible cap or summary.

Today we can stuff it into --background, but that's per-file and token-heavy, and not first-class. Native support — e.g. auto-detect AGENTS.md, or a config like context_files — would be cleaner and benefit everyone, not just our integration.

---

2. Spec-aware review via a spec ↔ file mapping

ocr's pipeline today is diff → changed files → per-file review. A big accuracy win would be: for each changed file, also feed the spec(s) that file implements, so the review can ask "does this change still satisfy the spec / requirement?" — not only "is this code locally OK?".

This needs two things:

1. A spec format/ruleset (requirements + scenarios, or a pointer to spec files).
2. A declared spec ↔ file mapping — which spec governs which files/paths — analogous to how .opencodereview/rule.json maps path globs → rules. For example a path-glob → spec-file(s) mapping, and ocr includes the matched specs as context for those files.

This would make ocr requirement-aware, a step beyond purely code-local review — and pairs naturally with spec-driven workflows.

---

Happy to discuss design and contribute a PR for either if you're open to it. Thanks again for ocr!

[lizhengfeng101]

Hi @qiankunli, thanks for the detailed write-up and for sharing how you've integrated ocr into devloop — really cool to see it used as a lifecycle hook in an aggregate-workspace workflow! 🙏

1. Auto-include AGENTS.md

We won't be supporting automatic inclusion of AGENTS.md for now. Our concern is that AGENTS.md files typically contain a lot of noise that isn't relevant to code review (agent routing rules, tool configurations, workflow instructions, etc.). To make it useful, we'd need an additional LLM-powered extraction step to pull out only the review-relevant conventions — but that step itself introduces its own accuracy risks and adds latency/cost to the pipeline.

That said, we do see the value here. We're likely to support this via a configuration parameter (e.g. context_files) in the future, so you can explicitly opt in and point ocr at the files you want included. This gives you control over what context gets fed in without the noise problem.

2. Spec ↔ file mapping for requirement-aware review

This is a genuinely interesting idea, and we appreciate you raising it. However, we've actually experimented with similar approaches internally, and our conclusion was that the side effects outweighed the benefits at this stage. The core challenge is twofold:

• User burden: maintaining an accurate spec ↔ file mapping adds significant overhead, especially as codebases evolve.
• LLM limitations: current models struggle with the cognitive jump between requirement-level reasoning and code-level review — the context switch tends to dilute review quality rather than improve it.

We believe this approach will become much more viable as foundation model capabilities continue to improve. We plan to revisit it when models can more reliably handle cross-domain reasoning at this scale. Stay tuned!

---

In the meantime, --background and custom rules via .opencodereview/rule.json remain the best levers for injecting domain context. Thanks again for using ocr and for the thoughtful suggestions!

[qiankunli]

Thanks @lizhengfeng101 — both concerns are fair, and I think the framing below sidesteps them.

Keep ocr's input simple. ocr would only ever read a spec.json — a sibling of rule.json (path → text, same glob machinery). It doesn't care where the file comes from, so the spec ↔ file mapping is never hand-maintained — it's a generated artifact.

Where it comes from. Specs/cases live co-located on the code they govern, as decorators (Python) or doc-comment markers (Go). A small, language-specific specgen statically extracts them into spec.json — entirely outside ocr.

@spec("GetNotebook: locate by NotebookID or Name; both empty -> 422; never cross tenant/user")
@case("both_empty", "both empty must be rejected by model_validator (422)")
@case("happy_by_name", "Name-only hits the same-named notebook under the current user")
async def get_notebook(...): ...

This is meant to address your two points:

• Maintenance / drift — because the spec sits on the function, there's no separate mapping to keep in sync; it's regenerated, and a specgen --check in CI can fail when code changed but the spec didn't.
• Cross-domain reasoning — the @cases turn "does this satisfy the spec?" into a concrete, per-function checklist. And since specgen resolves to the function level, ocr can feed only the changed function's cases — checklist-checking, not requirement-level reasoning.

By the way, I've also reached out over email — happy to chat through the details there whenever convenient. No rush at all if the timing isn't right; I'd be glad to prototype a Python specgen and a small ocr-side PR whenever you're open to it. 🙏