eandualem / eandualem/agent-backbone
feat: let repository agents run and retrieve Ultra reviews
- Dominant language
- Python
- Stars
- 5
- Forks
- 1
- Avg merge
- 38m
- Merged PRs (30d)
- 89
Description
[from:agent-backbone]
Repository agents should be able to start and inspect a thorough code review through backbone, as they can create and manage swarms, without asking the owner to run a separate terminal command.
The owner-run Codex review of develop against main on 2026-09-06 found five reproducible regressions despite 1,542 passing tests. It completed successfully, but the non-interactive command did not produce an obvious report file: a later session had to recover the findings from Codex session logs. Make review execution and result retrieval a supported agent capability.
## Scope
- Provide CLI/API operations to start a review, inspect progress, retrieve results and cancel a run. Expose the workflow in `backbone help` and the agent brief so repository agents can choose it when a change warrants deeper review. Command names and data model are to be designed during implementation.
- Support the verified Codex base-branch review with explicit model/reasoning effort, including Ultra where the installed model supports it. Investigate an adapter for Claude Code's native `ultrareview`, keeping the distinction between that capability and ordinary high-effort review explicit.
- Keep provider-specific commands, capability detection, configuration and output handling in runtime adapters. The backbone remains a control plane for installed CLIs.
- Capture the repository, immutable reviewed head, base/merge-base, runtime version, model, effort, timestamps, exit status and review outcome. Reject or clearly label results that no longer match the intended commit.
- Persist readable and structured findings plus execution logs in a documented backbone-owned location. Results must be retrievable after the invoking agent's turn ends or the backbone restarts; never rely on terminal scrollback or a private model session as the only report.
- Report queued/running/completed/failed/cancelled states truthfully, with bounded concurrency and configurable time/resource limits. Distinguish a clean review from a failed, interrupted, timed-out or unparsable run. Preserve partial diagnostics and distinguish findings from execution errors.
- Start the review with fresh context focused on the selected diff. Preserve the runtime sandbox and protect the implementation agent's identity: reviewer hooks must not overwrite the invoking agent's state, acknowledgments or shared handoff. Use separate reviewer state/artifacts and deliver a concise completion notice plus a result reference through the normal delivery gate.
- Default to read-only review with no automatic GitHub posting, implementation, merge or release. Follow existing agent/GitHub provenance and secret-handling rules. Identify required authentication and unavailable CLI capabilities with actionable errors.
## Acceptance criteria
1. A repository agent can initiate a develop-versus-main review, continue its work, then retrieve a completed report without the owner launching a terminal command.
2. Supported review adapters preserve the selected model/effort and record the exact commits actually reviewed.
3. Completed results survive a backbone restart and can be read from both CLI and API. Failed/interrupted runs never appear as successful clean reviews.
4. Caller state, sandbox protections, repository files and shared memory remain isolated from the reviewer; notifications wait while the caller is busy.
5. Tests cover command construction, capability failures, result parsing, persistence/recovery, cancellation/timeouts and stale-head detection without live services or model calls. Document a separate scratch-data live verification procedure.
6. Document when agents should choose a deep review versus an ordinary review or swarm, and how to inspect its findings before applying changes.
This is future feature work authorized by the owner. The five current release-review fixes belong in a separate PR against develop; this issue is not implemented or closed by that PR.
Contributor guide
Research direction
Start by reading the existing swarm CLI/API workflow, agent brief, runtime adapters, and current test structure. Define the review command and data model alongside adapter capability detection, then cover persistence, recovery, cancellation, stale-head handling, isolation, and parsing with tests that avoid live services. Done means agents can start, monitor, retrieve, and cancel durable reviews through both CLI and API with truthful outcomes and documented scratch-data verification.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, devtools, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100