atmos feat: add Claude agent for automated PR review and CI/CD remediation

what

Add a specialized Claude Code agent pr-review-remediator for automated PR review remediation
Create comprehensive agent in .claude/agents/pr-review-remediator.md with intelligent feedback analysis
Add slash command /fix-pr for quick PR remediation with cross-references
Implement CodeRabbit integration with AI prompt prioritization and validation framework
Add CodeQL security alert monitoring and remediation commands
Implement PR Semver Labels detection and automated suggestion logic
Add GitHub comment resolution to document and close addressed feedback
Handle deleted files properly in all PR operations
Enhance with robust bash patterns, strict mode, and improved error handling

why

Automate the repetitive task of addressing PR review feedback and CI/CD failures
Reduce manual effort in fixing linting issues, test failures, and security alerts
Ensure consistent application of project standards (CLAUDE.md requirements)
Speed up PR iteration cycles by providing validated, actionable remediation plans
Leverage CodeRabbit's AI prompts for understanding issues rather than blindly copying code
Provide intelligent label suggestions for semantic versioning requirements
Close the feedback loop by documenting what was fixed and resolving comments

Key Features

🤖 Intelligent CodeRabbit Integration

Prioritizes "Prompt for AI Agents" sections for understanding intent
Fetches both issue comments and inline review comments
Validates all suggestions against CLAUDE.md requirements with detailed checklist
Implements fixes based on understanding, not raw code copying
Presents analysis with clear Valid/Questionable/Skip categorization

🎯 Smart Targeted Operations

Only lints changed files in the PR (uses --new-from-rev=origin/main)
Excludes deleted files to prevent errors (uses GitHub API status filtering)
Runs tests only for affected packages with proper deduplication
Checks file existence before all operations
Uses robust bash patterns with IFS= and here-strings for reliability
Includes set -euo pipefail for bash strict mode error handling

🔒 Security & Compliance

CodeQL Integration: Fetches PR-specific security alerts with severity details
PR Semver Labels: Automated detection and suggestion based on commit patterns
Enhanced label logic recognizes breaking changes, features, and patches
Excludes .claude/ directory from documentation-only detection

💬 GitHub Comment Resolution

Reply to addressed comments with details of what was fixed
Post summary comments showing all remediated issues
Mark review threads as resolved using GitHub GraphQL API
Link fixes to commits for complete traceability
Creates audit trail of automated remediations

🛡️ Safety Controls

Always requires user approval before making changes
Never modifies golden snapshots in tests/test-cases/
Creates feature branches (never pushes to main)
Comprehensive validation checklist with ✅ and ⚠️ indicators
Tests fixes locally before committing

📊 Enhanced Analysis

Fetches all PR comments (CodeRabbit, human reviewers, inline comments)
Monitors GitHub status checks (tests, security, coverage, labels)
Creates actionable remediation plans with clear reasoning
Tracks progress using TodoWrite tool
YAML list format for tools for better parsing

Usage

# Method 1: Direct agent invocation
/agent pr-review-remediator

# Method 2: Slash command (action-oriented)
/fix-pr 1440

# Method 3: Natural language
"Please fix issues in PR #1440 based on review feedback"

Example Workflow

Gather: Agent fetches PR status, checks, and all feedback sources
Parse: Extracts and prioritizes CodeRabbit AI prompts over raw diffs
Validate: Checks each suggestion against comprehensive project standards
Analyze: Checks for conflicts, side effects, and backward compatibility
Present: Shows categorized plan (✅ Valid, ⚠️ Needs Review, ❌ Skip)
Approve: User reviews and approves specific fixes
Implement: Agent applies approved changes following CLAUDE.md requirements
Verify: Runs validation suite (lint changed files, test affected packages, build)
Document: Posts summary of fixes and replies to addressed comments
Resolve: Marks GitHub review threads as resolved

Recent Enhancements

Based on CodeRabbit Feedback (Dog-fooding)

✅ Fixed markdown linting violations (MD026, MD040)
✅ Standardized placeholder usage to <PR_NUMBER> throughout
✅ Converted tools to YAML list format
✅ Added inline comment fetching examples
✅ Improved bash loop patterns for robustness
✅ Enhanced label detection with more comprehensive patterns
✅ Expanded validation checklist with detailed criteria

Critical Fixes

✅ Deleted files handling: Filter by status != "removed" to prevent errors
✅ File existence checks: Verify files exist before format/lint/test operations
✅ Command naming: Renamed from /analyze-pr to /fix-pr for clarity
✅ Comment resolution: Added Phase 5 workflow to document and resolve feedback

File Structure

.claude/
├── agents/
│   └── pr-review-remediator.md    # Main PR review remediation agent
├── commands/
│   └── fix-pr.md                  # Slash command to fix PR issues
└── README.md                       # Documentation

references

Implements feedback handling patterns discussed in team reviews
Follows Claude Code agent best practices with YAML frontmatter
Successfully dog-fooded on its own PR to validate functionality
Addresses the need for automated PR feedback response at scale
Closes the feedback loop with comment resolution capabilities

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

Summary by CodeRabbit

Documentation
- Added a Claude PR Remediation documentation suite: agent spec, a slash-command for requesting fixes, and an overarching README describing usage and workflows.
- Documents user-facing invocation methods (agent, slash-command, natural prompts), CI/CD status monitoring, prioritized handling of AI and human review feedback, smart linting of changed files, validation/safety controls, example workflows, and customization guidance.
- Notes a minor discrepancy in the customization reference.

Sep 07 '25 14:09 osterman

📝 Walkthrough

Walkthrough

Adds a new .claude documentation suite for an automated PR remediation workflow: a pr-review-remediator agent spec, a slash-command fix-pr, and an overarching README describing invocation methods, validation rules, linting scope, status-check analysis, approval gating, and operational guidance.

Changes

Cohort / File(s)	Summary
Documentation root `.claude/README.md`	New README describing directory structure, usage (direct agent, `/fix-pr`, manual prompts), features, workflows, commands, validation process, safety controls, and customization notes (notes a customization path discrepancy referencing `analyze-pr.md` vs `fix-pr.md`).
Agent spec `.claude/agents/pr-review-remediator.md`	New agent blueprint defining responsibilities: parse CodeRabbit & human feedback, monitor GitHub status checks, generate remediation plans with validation, require user approval, lint only changed (non-deleted) files, avoid golden-test changes, and provide response/templates for reporting and thread resolution.
Command spec `.claude/commands/fix-pr.md`	New CLAUDE command `fix-pr` spec: fetch PR comments/statuses, identify failing checks, synthesize remediation plan (recommend using pr-review-remediator), present for approval, and run targeted lint/tests before committing fixes.

Sequence Diagram(s)

sequenceDiagram
    participant User as Developer / Reviewer
    participant CLI as Slash Command (/fix-pr)
    participant Agent as pr-review-remediator
    participant Repo as GitHub Repo
    participant CI as CI/CD & Tests

    CLI->>Agent: /fix-pr <PR>
    Agent->>Repo: fetch PR metadata, changed files, comments
    Agent->>Repo: parse CodeRabbit & human review comments
    Agent->>CI: check status checks, failing jobs
    Agent-->>Agent: generate remediation plan & validation summary
    Agent->>User: present plan (Requires approval)
    alt User approves
        User->>Agent: approve
        Agent->>Repo: create feature branch & apply fixes (commits)
        Agent->>CI: run lint/tests on changed files
        CI-->>Agent: results (pass/fail)
        Agent->>Repo: post remediation report & resolve threads
    else User rejects / requests changes
        User->>Agent: modify plan / cancel
        Agent->>User: update plan or abort
    end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

cloudposse/atmos#1419 — Adds CLAUDE.md guide referenced by these new docs (validation/standards used by the agent).

Suggested reviewers

aknysh
Gowiem
RoseSecurity

✨ Finishing Touches

🧪 Generate unit tests

[ ] Create PR with unit tests
[ ] Post copyable unit tests in a comment
[ ] Commit unit tests in branch agent-to-fix-reivew-comments

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

Sep 07 '25 14:09 coderabbitai[bot]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 55.95%. Comparing base (4cdbe27) to head (6ae31e2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1465   +/-   ##
=======================================
  Coverage   55.94%   55.95%           
=======================================
  Files         274      274           
  Lines       28936    28936           
=======================================
+ Hits        16189    16190    +1     
+ Misses      10955    10952    -3     
- Partials     1792     1794    +2

Flag	Coverage Δ
unittests	`55.95% <ø> (+<0.01%)`	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

:snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sep 07 '25 14:09 codecov[bot]