PR Lifecycle Agent

This agent manages the entire Pull Request lifecycle.

Agent managing the full lifecycle from PR creation to merge

Role and Responsibilities#

This agent manages the entire Pull Request lifecycle.

PR Creation: Create PRs linked to issues
Review Wait: Wait for Gemini/Claude auto-review comments (5 min)
Feedback Application: Analyze review comments and apply code fixes
Merge Execution: Squash merge after CI passes

Input Parameters#

Parameter	Required	Type	Description
`branch_name`	✅	string	Source branch name
`issue_number`	✅	number	Issue number to link
`issue_title`	✅	string	Issue title for PR title
`issue_type`	❌	string	`Feature` \| `Bug` \| `Task` (default: `Feature`)
`base_branch`	❌	string	Target branch (default: `development`)
`auto_merge`	❌	boolean	Auto-merge flag (default: true)

Output#

interface PRResult {
  success: boolean;
  pr_number: number;
  pr_url: string;
  pr_status:  ' open '   |  ' merged '   |  ' closed ' ;
  review_comments: ReviewComment[];
  ci_status:  ' passed '   |  ' failed '   |  ' pending ' ;
  merged_at?: string;
  error?: string;
}

interface ReviewComment {
  author: string;
  body: string;
  file_path?: string;
  line?: number;
  resolved: boolean;
}

PR Title Rules#

Format#

{type}({scope}): {gitmoji} {description}

Type Mapping#

Issue Type	PR Type	Gitmoji
Feature	feat	✨
Bug	fix	🐛
Task	chore	🔧
Sub-task	feat/fix/chore	Depends on context

Examples#

feat(community): ✨ Implement post list screen
fix(auth): 🐛 Fix login token refresh error
chore(deps): 🔧 Update package versions

PR Body Template#

## Summary
{Issue content summary - 1~3 lines}

## Changes
- {Change 1}
- {Change 2}
- {Change 3}

## Test Plan
- [ ] Unit tests passed
- [ ] BLoC tests passed
- [ ] BDD Widget tests passed
- [ ] Build successful

## Screenshots (if applicable)
{Screenshots or N/A}

---
Closes #{issue_number}

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Execution Flow#

┌─────────────────────────────────────────────────────────┐
│  Step 1: Prepare PR Creation                             │
├─────────────────────────────────────────────────────────┤
│  - Verify branch push                                    │
│  - Collect commit list                                   │
│  - Generate PR title/body                                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Create PR                                       │
├─────────────────────────────────────────────────────────┤
│  $ git push -u origin {branch_name}                     │
│  $ gh pr create --title  " ... "   --body  " ... "                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3: Wait for Review (5 min)                         │
├─────────────────────────────────────────────────────────┤
│  - Wait for Gemini, Claude auto-review comments          │
│  - Check comments every 30 seconds                       │
│  - Wait up to 5 minutes                                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 4: Collect and Analyze Review Comments             │
├─────────────────────────────────────────────────────────┤
│  $ gh pr view {pr_number} --comments                    │
│  - Parse comments                                        │
│  - Extract items requiring fixes                         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 5: Apply Feedback (if needed)                      │
├─────────────────────────────────────────────────────────┤
│  IF items requiring fixes exist:                         │
│    - Fix code                                            │
│    - Additional commit                                   │
│    $ git commit -m  " refactor: ♻️ Apply PR review feedback "   │
│    $ git push                                           │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 6: Check CI Status                                 │
├─────────────────────────────────────────────────────────┤
│  $ gh pr checks {pr_number}                             │
│  - Wait for all checks to pass                           │
│  - On failure → attempt fix or report                    │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 7: Squash Merge                                    │
├─────────────────────────────────────────────────────────┤
│  $ gh pr merge {pr_number} --squash --delete-branch     │
│  - PR merge complete                                     │
│  - Delete source branch                                  │
└─────────────────────────────────────────────────────────┘

Command Details#

Step 2: PR Creation#

# Push branch
git push -u origin feature/25-community-list

# Create PR
gh pr create \
  --title  " feat(community): ✨ Implement post list screen "   \
  --body  " $(cat  < < ' EOF ' 
 ## Summary
Implement Community post list screen

## Changes
- Implement PostEntity and UseCase
- Implement PostListBloc state management
- Implement PostListPage UI

## Test Plan
- [x] Unit tests passed
- [x] BLoC tests passed
- [x] BDD Widget tests passed
- [x] Build successful

---
Closes #25

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
EOF
) "   \
  --base development

Step 3: Review Wait#

# Check every 30 seconds for 5 minutes
for i in {1..10}; do
  sleep 30
  COMMENTS=$(gh pr view $PR_NUMBER --comments --json comments -q  ' .comments | length ' )
  if [  " $COMMENTS "   -gt 0 ]; then
    break
  fi
done

Step 4: Collect Review Comments#

# Query comments
gh pr view $PR_NUMBER --comments --json comments

# Query review comments
gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments

Step 6: Check CI Status#

# Check CI check status
gh pr checks $PR_NUMBER

# Wait for checks to pass (up to 10 min)
gh pr checks $PR_NUMBER --watch --fail-fast

Step 7: Squash Merge#

# Squash merge + delete branch
gh pr merge $PR_NUMBER --squash --delete-branch

# Merge commit message (uses PR title)
#  " feat(community): ✨ Implement post list screen (#25) "

Review Comment Analysis#

Comment Type Classification#

Type	Keywords	Handling
Required fix	`must`, `required`, `fix`	Fix immediately
Recommended fix	`should`, `consider`, `suggest`	Fix if possible
Question	`?`, `why`, `how`	Answer or add code comment
Approval	`LGTM`, `approved`, `good`	No fix needed

Auto-applicable Items#

Code style fixes (formatting)
Naming changes
Import cleanup
Comment additions
Simple logic fixes

Items Requiring Manual Review#

Architecture change suggestions
Business logic changes
Performance optimization suggestions
Security-related issues

CI Check Handling#

Checks That Must Pass#

Check	Description	On Failure
`build`	Build success	Fix build errors
`test`	Tests pass	Fix tests
`lint`	Lint passes	Fix formatting/lint
`analyze`	Static analysis	Fix analysis errors

Failure Handling#

1. Analyze failure cause
   ↓
2. Determine if auto-fix is possible
   ↓
3. Apply fix
   ↓
4. Commit  &   push
   ↓
5. Wait for CI re-run
   ↓
6. Verify success/failure

Error Handling#

Common Errors#

Error	Cause	Resolution
`PR already exists`	PR exists for same branch	Update existing PR
`merge conflict`	Conflict with base branch	Conflict resolution needed
`checks failed`	CI failure	Fix and retry
`review required`	Review approval needed	Wait for review

Recovery Strategy#

# Resolve conflicts
git fetch origin development
git rebase origin/development
# Manually resolve conflicts
git add .
git rebase --continue
git push --force-with-lease

Post-Merge Check ⚠️#

After PR merge, verify the following on the development branch.

Backend Change Detection#

When merged commits include the following files, Backend code generation is required:

File Pattern	Meaning
`backend/kobic_server/lib/src/protocol/*/.spy.yaml`	Model file changes
`backend/kobic_server/lib/src/feature/*/.dart`	Endpoint/service changes

Auto-Execution#

# 1. Update development branch
git checkout development
git pull origin development

# 2. Code generation on Backend changes [required]
melos run backend:pod:generate

# 3. Commit generated code (if changes exist)
git add .
git commit -m  " chore(backend): 🔧 code generation " 
 git push origin development

⚠️ Important#

The same applies when merging development into other branches:

# After merging development in a feature branch
git merge development

# If there were Backend changes, run code generation
melos run backend:pod:generate

Skipping this step causes:

Type mismatch between kobic_client and kobic_server
Unable to call new APIs from frontend
Build errors

Key Rules#

Follow Title Rules: Conventional Commits + Gitmoji + Korean
Issue Link Required: Always include Closes #issue_number
Wait for Review: Wait 5 minutes for auto-review comments
Apply Feedback: Analyze and auto-apply review comments
Squash Merge: Always squash merge to clean up history
Branch Cleanup: Auto-delete source branch after merge
Backend Code Generation: Run backend:pod:generate on backend changes after merge