Agent-Loop: Introduction to the Claude-Based Automated PR Review and Merge Workflow System

Agent-Loop is a reusable GitHub Actions workflow system whose core goal is to implement AI-driven automated PR review, repair, and merge, while solving repetitive review issues in large-scale software development. Its key features include: dual-robot identity separation to ensure process compliance, support for progressive automated deployment, and a comprehensive manual intervention mechanism. This system aims to assist human reviewers, allowing teams to focus on work that requires judgment.

Project Background and Objectives

Agent-Loop was developed by RiddimSoftware to address repetitive review work in large-scale software development. Version 0.1 sets clear success criteria: within a two-week window, achieve 10 consecutive PRs merged autonomously without manual hotfixes to workflow files. This goal reflects the team's clear understanding of the boundaries of AI automation.

Core Architecture Design and Workflow Components

Dual Robot Identity Separation

A unique dual-robot architecture is adopted to ensure security and compliance:

Robot Identity	GitHub Account	Core Responsibilities
developer-bot	riddim-riddim-developer-bot[bot]	Create PRs, push implementation branches, trigger workflows
reviewer-bot	riddim-riddim-reviewer-bot[bot]	Run Claude reviews, push fix commits, approve PRs
This design avoids the GitHub restriction of the same identity both creating and approving PRs.

Core Workflow Components

It includes four closed-loop workflows:

1. agent-review.yml: Claude-driven intelligent review, triggered after pr-build succeeds, handling review, repair, and approval.
2. reviewer.yml: Mechanized merge manager, checking mergeable_state to decide the next step.
3. conflict-scan.yml: Intelligent conflict resolver, handling PR conflicts when the main branch is updated.
4. pr-build.yml: Self-test workflow, verifying changes to agent-loop itself.

Complete Workflow Execution Process

The execution process is as follows:

1. developer-bot creates a PR (branch claude/ with the autonomous tag) → pr-build succeeds.
2. agent-review.yml is triggered: read diff → Claude review → if approved, push fixes, execute approve, and enable auto-merge; if human intervention is needed, add the agent:needs-human tag.
3. reviewer.yml intervenes: check mergeable_state → dirty branches retain the autonomous tag for conflict-scan processing.
4. When the main branch advances, conflict-scan.yml runs: poll PR status → if approved + CI passed + dirty branch, developer-bot performs rebase/conflict resolution; if failed, add the agent:needs-human tag.
5. After synchronization, re-review is conducted, and GitHub auto-merge is triggered after gatekeeping passes.

Usage Guide and Configuration Key Points

Consumer Repository Configuration

1. Create a workflow wrapper (e.g., .github/workflows/agent-loop.yml).
2. Set the repository variable LOOP_OPENER_ALLOWLIST (list of login names allowed to trigger).
3. Create necessary tags: autonomous, agent:pause, agent:needs-human, agent:attempt-1..3.
4. Configure organization secrets REVIEWER_BOT_APP_ID and REVIEWER_BOT_PRIVATE_KEY.

Version Alignment and Asset Separation

• Version Alignment: Specify the runtime asset version via the agent_loop_ref parameter to ensure synchronization between uses and ref.
• Asset Separation: The consumer repository checks out the code to be reviewed, while the agent-loop repository provides runtime assets (prompts, scripts) to keep the consumer repository clean.

Intervention Mechanisms and Limitations

Intervention Mechanisms

• Global Pause: Add the agent:pause tag to the PR, and all workflows exit short-circuited.
• Single PR Removal: Add the agent:needs-human tag to remove automation for a specific PR.
• Failure Handling: When conflict resolution or review fails, automatically add the agent:needs-human tag and comment on the reason.

Limitations

• Version 0.1 has limited functionality; complex reviews require human intervention.
• Currently dependent on Claude; future support for model routing.
• Requires a GitHub-hosted Ubuntu runner.
• Complex organization configuration (secrets, tags, allowlists, etc.).

Roadmap and Conclusion

v0.2 Roadmap

Planned features for return:

Feature	Description
Jira Integration Trigger	Jira Automation → repository_dispatch → create-pr.yml
Change Request Ping-Pong	Reviewer requests changes → developer iterates → re-review cycle
Multi-Round Reviews	Support multi-round reviews for a single PR
Multi-Consumer Promotion	Expand to epac, riddim-website, etc.
PAT Rotation	Consumer-level PAT + 90-day rotation strategy

Conclusion

Agent-Loop represents an important direction in AI-assisted software engineering: not replacing humans, but handling repetitive tasks so that humans can focus on work requiring judgment and creativity. Its dual-robot architecture, intervention mechanisms, and evolution roadmap provide teams with a practical and scalable AI automation solution.