[V2] Add comprehensive Git/PR workflow CLI commands

[frankbria]

🎯 Overview

Add comprehensive CLI commands for Git/PR workflow management to complete Phase 5 of the enhanced MVP. GitHub integration exists but lacks CLI interface for user interaction.

📊 Current State Analysis

Existing Implementation: GitHub integration module at `codeframe/git/github_integration.py`
Current Features:

• GitHub API client for PR operations
• Basic PR data structures and models
• Integration with existing git operations
• Server-side endpoints for PR management

Identified Gaps:

• No CLI commands for PR creation, listing, management
• No automatic branch creation with naming conventions
• No AI-generated PR descriptions with business impact
• No automated PR labeling and reviewer assignment
• No integration with CI/CD pipeline gate execution
• No multi-strategy merge support (squash, merge, rebase)

📋 Implementation Requirements

Phase 1: Branch Management Integration

• Add `codeframe work start --create-branch` functionality
• Implement automatic branch creation with consistent naming conventions
• Add branch cleanup and organization utilities
• Integrate branch creation with task and batch execution
• Add conflict detection and resolution assistance
• Support for feature branch workflow patterns

Phase 2: PR Creation CLI Interface

• Create `codeframe/cli/pr_commands.py` module
• Add `codeframe pr create` command with AI description generation
• Implement `codeframe pr list [--status open|closed|merged]` for PR management
• Add AI-generated comprehensive PR descriptions with:
  • Business impact and value proposition
  • Technical implementation details
  • Testing performed and results
  • Breaking changes and migration notes
• Add automated PR labeling and categorization
• Implement reviewer assignment based on code expertise

Phase 3: PR Management Operations

• Add `codeframe pr merge [--strategy squash|merge|rebase]` command
• Implement automated verification gate execution before merge
• Add CI/CD pipeline integration and gate coordination
• Support for merge strategy selection and conflict resolution
• Add post-merge cleanup and notification automation
• Implement PR status tracking and monitoring

Phase 4: AI Integration & Automation

• Enhance AI description generation with business context
• Add impact analysis and change summary generation
• Implement automated labeling based on content analysis
• Add reviewer expertise matching and assignment
• Integrate with existing task and batch execution systems
• Add PR template and automation features

🔗 Dependencies

• Builds on existing `codeframe/git/github_integration.py` infrastructure
• Must integrate with existing batch execution and checkpoint systems
• Should work with existing workspace and state management
• Benefits from enhanced credential management for GitHub access
• Requires AI systems for description generation

✅ Acceptance Criteria

• `codeframe work start --create-branch` creates feature branches automatically
• `codeframe pr create` generates AI-enhanced descriptions and creates PRs
• `codeframe pr merge` handles all merge strategies with validation
• PR descriptions include business impact and technical details
• Automated labeling and reviewer assignment works reliably
• Integration with CI/CD pipelines coordinates gate execution
• Branch management follows consistent naming conventions
• Comprehensive test coverage for all Git/PR workflow scenarios

🎯 Success Metrics

• Eliminates manual PR creation and management overhead
• Improves PR quality with AI-generated comprehensive descriptions
• Reduces merge conflicts through better branch management
• Automates code review workflow and reviewer assignment
• Provides consistent Git workflow across all projects
• Enables reliable CI/CD integration and gate coordination

📚 References

• Enhanced MVP specification: `docs/GOLDEN_PATH.md`
• GitHub integration: `codeframe/git/github_integration.py`
• Gap analysis: `docs/GAP_ANALYSIS_SUMMARY.md`
• Implementation roadmap: `docs/IMPLEMENTATION_ROADMAP.md`
• CLI wireframe: `docs/CLI_WIREFRAME.md`

This is high priority as it completes the Git/PR workflow that users need for the final stages of the enhanced MVP.

[traycerai]

Plan

Observations

The codebase has robust GitHub integration infrastructure with GitHubIntegration class (file:codeframe/git/github_integration.py), PRRepository for database operations (file:codeframe/persistence/repositories/pr_repository.py), and FastAPI endpoints (file:codeframe/ui/routers/prs.py). However, there are no CLI commands for PR operations. The CLI follows a Typer-based pattern with command groups registered in file:codeframe/cli/init.py. AI integration exists through AnthropicProvider (file:codeframe/providers/anthropic.py) and LeadAgent (file:codeframe/agents/lead_agent.py) which already generates PRDs and performs analysis. The GitWorkflowManager (file:codeframe/git/workflow_manager.py) handles branch creation with naming conventions but lacks CLI integration.

Approach

The implementation will create a new CLI command group codeframe pr following the established pattern in file:codeframe/cli/tasks_commands.py. This will wrap existing GitHub integration infrastructure while adding AI-powered description generation using the existing AnthropicProvider. Branch management will be integrated into task/work commands by extending the workflow manager. The approach prioritizes reusing existing infrastructure (GitHub API client, database repositories, AI provider) rather than rebuilding, ensuring consistency with the codebase's architecture. Quality gates and CI/CD integration will leverage existing review/gate infrastructure from file:docs/CLI_WIREFRAME.md.

Implementation Plan

Phase 1: Create PR CLI Command Module

Create file:codeframe/cli/pr_commands.py following the established Typer command group pattern:

Command Structure:

• pr_app = typer.Typer() - Main PR command group
• Import dependencies: APIClient, helpers.console, GitHubIntegration, AnthropicProvider, GlobalConfig
• Follow authentication pattern from file:codeframe/cli/tasks_commands.py using require_auth(client)

Register Command Group:

• Add import in file:codeframe/cli/init.py: from codeframe.cli.pr_commands import pr_app
• Register with: app.add_typer(pr_app, name="pr", help="Pull request management (create, list, merge)")

Phase 2: Implement codeframe pr create Command

Command Signature:

@pr_app.command("create")
def create_pr(
    branch: str = typer.Option(None, "--branch", "-b", help="Branch name (defaults to current)"),
    title: str = typer.Option(None, "--title", "-t", help="PR title"),
    base: str = typer.Option("main", "--base", help="Base branch"),
    auto_description: bool = typer.Option(True, "--auto-description/--no-auto-description"),
    project_id: int = typer.Option(None, "--project", "-p", help="Project ID"),
)

Implementation Steps:

1. Branch Detection: Use GitWorkflowManager.get_current_branch() to detect current branch if not specified

2. GitHub Configuration: Load from GlobalConfig (file:codeframe/core/config.py) - validate github_token and github_repo exist

3. AI Description Generation (if auto_description=True):

   • Collect git diff: git diff {base}...{branch}
   • Collect commit messages: git log {base}..{branch} --oneline
   • Query database for related tasks/issues using PRRepository and TaskRepository
   • Build prompt for AnthropicProvider:

     Generate a comprehensive PR description for the following changes:
     
     Branch: {branch}
     Commits: {commit_list}
     Diff Summary: {diff_stats}
     Related Tasks: {task_titles}
     
     Include:
     1. Business Impact & Value Proposition
     2. Technical Implementation Details
     3. Testing Performed
     4. Breaking Changes (if any)
     5. Migration Notes (if applicable)
     

   • Call provider.send_message() to generate description
   • Extract title from first line if not provided

4. PR Creation:

   • Initialize GitHubIntegration(token, repo)
   • Call await gh.create_pull_request(branch, title, body, base)
   • Store in database via PRRepository.create_pr()
   • Display success with PR URL and number

5. Error Handling: Catch GitHubAPIError, AuthenticationError, configuration errors with helpful messages

Phase 3: Implement codeframe pr list Command

Command Signature:

@pr_app.command("list")
def list_prs(
    status: str = typer.Option("open", "--status", "-s", help="Filter: open, closed, merged, all"),
    project_id: int = typer.Option(None, "--project", "-p"),
    format: str = typer.Option("table", "--format", "-f", help="Output: table or json"),
)

Implementation:

• Query PRRepository.list_prs(project_id, status) from database
• Optionally sync with GitHub API using GitHubIntegration.list_pull_requests(state)
• Display Rich table with columns: PR#, Title, Branch, Status, Created, URL
• Support JSON output for scripting

Phase 4: Implement codeframe pr merge Command

Command Signature:

@pr_app.command("merge")
def merge_pr(
    pr_number: int = typer.Argument(..., help="PR number to merge"),
    strategy: str = typer.Option("squash", "--strategy", "-s", help="Merge strategy: squash, merge, rebase"),
    skip_gates: bool = typer.Option(False, "--skip-gates", help="Skip quality gate checks"),
    project_id: int = typer.Option(None, "--project", "-p"),
)

Implementation:

1. Pre-merge Validation:

   • Fetch PR details from PRRepository.get_pr_by_number()
   • Verify PR is in "open" state
   • Check for merge conflicts via GitHub API

2. Quality Gate Execution (unless skip_gates=True):

   • Reference gate execution pattern from file:docs/CLI_WIREFRAME.md
   • Run codeframe.core.gates.run() if available
   • Check for test failures, lint errors
   • Display gate results and prompt for confirmation if failures exist

3. Merge Execution:

   • Call GitHubIntegration.merge_pull_request(pr_number, method=strategy)
   • Update database: PRRepository.update_pr_status(pr_id, "merged", merge_commit_sha)
   • Display merge commit SHA and success message

4. Post-merge Cleanup:

   • Optionally delete feature branch (with confirmation)
   • Update related tasks to "MERGED" status if linked

Phase 5: Implement codeframe pr get Command

Command Signature:

@pr_app.command("get")
def get_pr(
    pr_number: int = typer.Argument(..., help="PR number"),
    project_id: int = typer.Option(None, "--project", "-p"),
    format: str = typer.Option("text", "--format", "-f"),
)

Implementation:

• Fetch from database: PRRepository.get_pr_by_number()
• Optionally sync with GitHub: GitHubIntegration.get_pull_request()
• Display detailed PR information: title, body, status, commits, reviewers, checks

Phase 6: Integrate Branch Creation with Work Commands

Create file:codeframe/cli/work_commands.py (new module):

@work_app.command("start")
def start_work(
    task_id: int = typer.Argument(..., help="Task ID to start"),
    create_branch: bool = typer.Option(False, "--create-branch", "-b", help="Create feature branch"),
    project_id: int = typer.Option(None, "--project", "-p"),
)

Implementation:

1. Task Validation: Fetch task from TaskRepository.get_task(task_id)

2. Branch Creation (if create_branch=True):

   • Generate branch name using GitWorkflowManager._sanitize_branch_name()
   • Format: task-{task_id}-{sanitized-title} or issue-{issue_number}-{title}
   • Call GitWorkflowManager.create_feature_branch()
   • Checkout new branch
   • Store branch association in database

3. Task Status Update: Transition to IN_PROGRESS via state machine

4. Agent Execution: Integrate with existing runtime/agent execution (if available)

5. Display: Show branch name, task status, next steps

Register Work Commands:

• Add to file:codeframe/cli/init.py: app.add_typer(work_app, name="work", help="Work on tasks (start, resume, stop)")

Phase 7: Add AI-Powered PR Enhancement Features

Create file:codeframe/lib/pr_description_generator.py:

Class Structure:

class PRDescriptionGenerator:
    def __init__(self, provider: AnthropicProvider, repo_path: Path, db: Database)
    
    async def generate_description(
        self, 
        branch: str, 
        base: str, 
        task_ids: List[int] = None
    ) -> Dict[str, str]

Methods:

1. _collect_changes():

   • Git diff statistics
   • File change summary
   • Commit messages
   • Lines added/removed

2. _collect_context():

   • Related tasks from database
   • Issue descriptions
   • PRD sections (if linked)
   • Previous PR descriptions for consistency

3. _build_prompt():

   • Structured prompt with sections
   • Include codebase context
   • Request specific format (markdown sections)

4. _parse_response():

   • Extract title (first line or H1)
   • Extract body (remaining content)
   • Validate markdown structure

5. generate_labels():

   • Analyze changes to suggest labels
   • Categories: feature, bugfix, refactor, docs, test, breaking-change
   • Return list of suggested labels

6. suggest_reviewers():

   • Analyze file changes
   • Query git blame for file ownership
   • Match against team expertise (if configured)
   • Return list of suggested reviewer usernames

Phase 8: Add Advanced PR Management Commands

Additional Commands in file:codeframe/cli/pr_commands.py:

1. codeframe pr close:

   • Close PR without merging
   • Call GitHubIntegration.close_pull_request()
   • Update database status

2. codeframe pr update:

   • Update PR title/description
   • Regenerate description with AI
   • Add labels, reviewers

3. codeframe pr status:

   • Show PR checks status
   • Display CI/CD pipeline results
   • Show review status

Phase 9: CI/CD Gate Integration

Extend file:codeframe/core/gates.py (or create if missing):

Add PR-specific gates:

class PRGateRunner:
    async def run_pr_gates(self, pr_number: int) -> GateResult

Gate Types:

1. Test Gates: Run pytest, coverage checks
2. Lint Gates: Run linters, formatters
3. Security Gates: Dependency scanning, secret detection
4. Build Gates: Verify build succeeds
5. Custom Gates: User-defined scripts

Integration Points:

• Call from codeframe pr merge before merging
• Display gate results in Rich table
• Allow override with --skip-gates flag
• Store gate results in database for audit

Phase 10: Testing & Documentation

Test Files to Create:

1. file:tests/cli/test_pr_commands.py:

   • Test all PR commands with mocked GitHub API
   • Test error handling
   • Test AI description generation
   • Test gate integration

2. file:tests/cli/test_work_commands.py:

   • Test branch creation
   • Test task integration
   • Test workflow manager integration

3. file:tests/lib/test_pr_description_generator.py:

   • Test prompt building
   • Test response parsing
   • Test label/reviewer suggestion

Documentation Updates:

1. file:docs/CLI_WIREFRAME.md: Add PR command section
2. file:README.md: Add PR workflow examples
3. Create file:docs/PR_WORKFLOW.md: Comprehensive PR workflow guide

Implementation Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as PR Commands
    participant AI as AnthropicProvider
    participant GH as GitHubIntegration
    participant DB as PRRepository
    participant Git as GitWorkflowManager

    User->>CLI: codeframe work start --create-branch
    CLI->>Git: create_feature_branch()
    Git->>DB: store branch association
    Git-->>CLI: branch created
    CLI-->>User: Branch created, task started

    User->>CLI: codeframe pr create --auto-description
    CLI->>Git: get current branch & diff
    CLI->>DB: fetch related tasks
    CLI->>AI: generate_description(changes, context)
    AI-->>CLI: title + description
    CLI->>GH: create_pull_request()
    GH-->>CLI: PR details
    CLI->>DB: store PR record
    CLI-->>User: PR created with URL

    User->>CLI: codeframe pr merge <number>
    CLI->>DB: get PR details
    CLI->>CLI: run_pr_gates()
    CLI-->>User: display gate results
    User->>CLI: confirm merge
    CLI->>GH: merge_pull_request()
    GH-->>CLI: merge result
    CLI->>DB: update PR status
    CLI-->>User: PR merged successfully

Loading

Configuration Requirements

Environment Variables (add to file:.env.example):

# GitHub Integration
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
GITHUB_REPO=owner/repo-name

# PR Workflow Settings (optional)
PR_DEFAULT_BASE=main
PR_AUTO_DELETE_BRANCH=false
PR_REQUIRE_GATES=true

Project Config (extend file:codeframe/core/config.py):

class PRWorkflowConfig(BaseModel):
    default_base_branch: str = "main"
    auto_delete_merged_branches: bool = False
    require_gates_before_merge: bool = True
    default_merge_strategy: str = "squash"
    enable_ai_descriptions: bool = True

Error Handling Strategy

Common Error Scenarios:

1. GitHub Not Configured: Display helpful message with setup instructions
2. Branch Not Found: Suggest creating branch or checking branch name
3. PR Already Exists: Show existing PR URL
4. Merge Conflicts: Display conflict files, suggest resolution steps
5. Gate Failures: Show detailed failure reasons, allow override
6. API Rate Limits: Implement retry with exponential backoff
7. Network Errors: Graceful degradation, cache locally

Key Files Summary

New Files:

• file:codeframe/cli/pr_commands.py - PR CLI commands
• file:codeframe/cli/work_commands.py - Work/task CLI commands
• file:codeframe/lib/pr_description_generator.py - AI description generation
• file:tests/cli/test_pr_commands.py - PR command tests
• file:tests/cli/test_work_commands.py - Work command tests
• file:docs/PR_WORKFLOW.md - PR workflow documentation

Modified Files:

• file:codeframe/cli/init.py - Register new command groups
• file:codeframe/core/config.py - Add PR workflow configuration
• file:codeframe/git/workflow_manager.py - Enhance branch management
• file:docs/CLI_WIREFRAME.md - Document new commands
• file:.env.example - Add GitHub configuration examples

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has robust GitHub integration infrastructure with `GitHubIntegration` class (file:codeframe/git/github_integration.py), `PRRepository` for database operations (file:codeframe/persistence/repositories/pr_repository.py), and FastAPI endpoints (file:codeframe/ui/routers/prs.py). However, there are no CLI commands for PR operations. The CLI follows a Typer-based pattern with command groups registered in file:codeframe/cli/__init__.py. AI integration exists through `AnthropicProvider` (file:codeframe/providers/anthropic.py) and `LeadAgent` (file:codeframe/agents/lead_agent.py) which already generates PRDs and performs analysis. The `GitWorkflowManager` (file:codeframe/git/workflow_manager.py) handles branch creation with naming conventions but lacks CLI integration.

## Approach

The implementation will create a new CLI command group `codeframe pr` following the established pattern in file:codeframe/cli/tasks_commands.py. This will wrap existing GitHub integration infrastructure while adding AI-powered description generation using the existing `AnthropicProvider`. Branch management will be integrated into task/work commands by extending the workflow manager. The approach prioritizes reusing existing infrastructure (GitHub API client, database repositories, AI provider) rather than rebuilding, ensuring consistency with the codebase's architecture. Quality gates and CI/CD integration will leverage existing review/gate infrastructure from file:docs/CLI_WIREFRAME.md.

## Implementation Plan

### Phase 1: Create PR CLI Command Module

Create file:codeframe/cli/pr_commands.py following the established Typer command group pattern:

**Command Structure:**
- `pr_app = typer.Typer()` - Main PR command group
- Import dependencies: `APIClient`, `helpers.console`, `GitHubIntegration`, `AnthropicProvider`, `GlobalConfig`
- Follow authentication pattern from file:codeframe/cli/tasks_commands.py using `require_auth(client)`

**Register Command Group:**
- Add import in file:codeframe/cli/__init__.py: `from codeframe.cli.pr_commands import pr_app`
- Register with: `app.add_typer(pr_app, name="pr", help="Pull request management (create, list, merge)")`

### Phase 2: Implement `codeframe pr create` Command

**Command Signature:**
```
@pr_app.command("create")
def create_pr(
    branch: str = typer.Option(None, "--branch", "-b", help="Branch name (defaults to current)"),
    title: str = typer.Option(None, "--title", "-t", help="PR title"),
    base: str = typer.Option("main", "--base", help="Base branch"),
    auto_description: bool = typer.Option(True, "--auto-description/--no-auto-description"),
    project_id: int = typer.Option(None, "--project", "-p", help="Project ID"),
)
```

**Implementation Steps:**

1. **Branch Detection**: Use `GitWorkflowManager.get_current_branch()` to detect current branch if not specified
2. **GitHub Configuration**: Load from `GlobalConfig` (file:codeframe/core/config.py) - validate `github_token` and `github_repo` exist
3. **AI Description Generation** (if `auto_description=True`):
   - Collect git diff: `git diff {base}...{branch}`
   - Collect commit messages: `git log {base}..{branch} --oneline`
   - Query database for related tasks/issues using `PRRepository` and `TaskRepository`
   - Build prompt for `AnthropicProvider`:
     ```
     Generate a comprehensive PR description for the following changes:
     
     Branch: {branch}
     Commits: {commit_list}
     Diff Summary: {diff_stats}
     Related Tasks: {task_titles}
     
     Include:
     1. Business Impact & Value Proposition
     2. Technical Implementation Details
     3. Testing Performed
     4. Breaking Changes (if any)
     5. Migration Notes (if applicable)
     ```
   - Call `provider.send_message()` to generate description
   - Extract title from first line if not provided

4. **PR Creation**: 
   - Initialize `GitHubIntegration(token, repo)`
   - Call `await gh.create_pull_request(branch, title, body, base)`
   - Store in database via `PRRepository.create_pr()`
   - Display success with PR URL and number

5. **Error Handling**: Catch `GitHubAPIError`, `AuthenticationError`, configuration errors with helpful messages

### Phase 3: Implement `codeframe pr list` Command

**Command Signature:**
```
@pr_app.command("list")
def list_prs(
    status: str = typer.Option("open", "--status", "-s", help="Filter: open, closed, merged, all"),
    project_id: int = typer.Option(None, "--project", "-p"),
    format: str = typer.Option("table", "--format", "-f", help="Output: table or json"),
)
```

**Implementation:**
- Query `PRRepository.list_prs(project_id, status)` from database
- Optionally sync with GitHub API using `GitHubIntegration.list_pull_requests(state)`
- Display Rich table with columns: PR#, Title, Branch, Status, Created, URL
- Support JSON output for scripting

### Phase 4: Implement `codeframe pr merge` Command

**Command Signature:**
```
@pr_app.command("merge")
def merge_pr(
    pr_number: int = typer.Argument(..., help="PR number to merge"),
    strategy: str = typer.Option("squash", "--strategy", "-s", help="Merge strategy: squash, merge, rebase"),
    skip_gates: bool = typer.Option(False, "--skip-gates", help="Skip quality gate checks"),
    project_id: int = typer.Option(None, "--project", "-p"),
)
```

**Implementation:**

1. **Pre-merge Validation**:
   - Fetch PR details from `PRRepository.get_pr_by_number()`
   - Verify PR is in "open" state
   - Check for merge conflicts via GitHub API

2. **Quality Gate Execution** (unless `skip_gates=True`):
   - Reference gate execution pattern from file:docs/CLI_WIREFRAME.md
   - Run `codeframe.core.gates.run()` if available
   - Check for test failures, lint errors
   - Display gate results and prompt for confirmation if failures exist

3. **Merge Execution**:
   - Call `GitHubIntegration.merge_pull_request(pr_number, method=strategy)`
   - Update database: `PRRepository.update_pr_status(pr_id, "merged", merge_commit_sha)`
   - Display merge commit SHA and success message

4. **Post-merge Cleanup**:
   - Optionally delete feature branch (with confirmation)
   - Update related tasks to "MERGED" status if linked

### Phase 5: Implement `codeframe pr get` Command

**Command Signature:**
```
@pr_app.command("get")
def get_pr(
    pr_number: int = typer.Argument(..., help="PR number"),
    project_id: int = typer.Option(None, "--project", "-p"),
    format: str = typer.Option("text", "--format", "-f"),
)
```

**Implementation:**
- Fetch from database: `PRRepository.get_pr_by_number()`
- Optionally sync with GitHub: `GitHubIntegration.get_pull_request()`
- Display detailed PR information: title, body, status, commits, reviewers, checks

### Phase 6: Integrate Branch Creation with Work Commands

**Create file:codeframe/cli/work_commands.py** (new module):

```
@work_app.command("start")
def start_work(
    task_id: int = typer.Argument(..., help="Task ID to start"),
    create_branch: bool = typer.Option(False, "--create-branch", "-b", help="Create feature branch"),
    project_id: int = typer.Option(None, "--project", "-p"),
)
```

**Implementation:**

1. **Task Validation**: Fetch task from `TaskRepository.get_task(task_id)`
2. **Branch Creation** (if `create_branch=True`):
   - Generate branch name using `GitWorkflowManager._sanitize_branch_name()`
   - Format: `task-{task_id}-{sanitized-title}` or `issue-{issue_number}-{title}`
   - Call `GitWorkflowManager.create_feature_branch()`
   - Checkout new branch
   - Store branch association in database

3. **Task Status Update**: Transition to `IN_PROGRESS` via state machine
4. **Agent Execution**: Integrate with existing runtime/agent execution (if available)
5. **Display**: Show branch name, task status, next steps

**Register Work Commands:**
- Add to file:codeframe/cli/__init__.py: `app.add_typer(work_app, name="work", help="Work on tasks (start, resume, stop)")`

### Phase 7: Add AI-Powered PR Enhancement Features

**Create file:codeframe/lib/pr_description_generator.py**:

**Class Structure:**
```python
class PRDescriptionGenerator:
    def __init__(self, provider: AnthropicProvider, repo_path: Path, db: Database)
    
    async def generate_description(
        self, 
        branch: str, 
        base: str, 
        task_ids: List[int] = None
    ) -> Dict[str, str]
```

**Methods:**

1. **`_collect_changes()`**: 
   - Git diff statistics
   - File change summary
   - Commit messages
   - Lines added/removed

2. **`_collect_context()`**:
   - Related tasks from database
   - Issue descriptions
   - PRD sections (if linked)
   - Previous PR descriptions for consistency

3. **`_build_prompt()`**:
   - Structured prompt with sections
   - Include codebase context
   - Request specific format (markdown sections)

4. **`_parse_response()`**:
   - Extract title (first line or H1)
   - Extract body (remaining content)
   - Validate markdown structure

5. **`generate_labels()`**: 
   - Analyze changes to suggest labels
   - Categories: feature, bugfix, refactor, docs, test, breaking-change
   - Return list of suggested labels

6. **`suggest_reviewers()`**:
   - Analyze file changes
   - Query git blame for file ownership
   - Match against team expertise (if configured)
   - Return list of suggested reviewer usernames

### Phase 8: Add Advanced PR Management Commands

**Additional Commands in file:codeframe/cli/pr_commands.py:**

1. **`codeframe pr close`**:
   - Close PR without merging
   - Call `GitHubIntegration.close_pull_request()`
   - Update database status

2. **`codeframe pr update`**:
   - Update PR title/description
   - Regenerate description with AI
   - Add labels, reviewers

3. **`codeframe pr status`**:
   - Show PR checks status
   - Display CI/CD pipeline results
   - Show review status

### Phase 9: CI/CD Gate Integration

**Extend file:codeframe/core/gates.py** (or create if missing):

**Add PR-specific gates:**
```python
class PRGateRunner:
    async def run_pr_gates(self, pr_number: int) -> GateResult
```

**Gate Types:**
1. **Test Gates**: Run pytest, coverage checks
2. **Lint Gates**: Run linters, formatters
3. **Security Gates**: Dependency scanning, secret detection
4. **Build Gates**: Verify build succeeds
5. **Custom Gates**: User-defined scripts

**Integration Points:**
- Call from `codeframe pr merge` before merging
- Display gate results in Rich table
- Allow override with `--skip-gates` flag
- Store gate results in database for audit

### Phase 10: Testing & Documentation

**Test Files to Create:**

1. **file:tests/cli/test_pr_commands.py**:
   - Test all PR commands with mocked GitHub API
   - Test error handling
   - Test AI description generation
   - Test gate integration

2. **file:tests/cli/test_work_commands.py**:
   - Test branch creation
   - Test task integration
   - Test workflow manager integration

3. **file:tests/lib/test_pr_description_generator.py**:
   - Test prompt building
   - Test response parsing
   - Test label/reviewer suggestion

**Documentation Updates:**

1. **file:docs/CLI_WIREFRAME.md**: Add PR command section
2. **file:README.md**: Add PR workflow examples
3. **Create file:docs/PR_WORKFLOW.md**: Comprehensive PR workflow guide

### Implementation Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as PR Commands
    participant AI as AnthropicProvider
    participant GH as GitHubIntegration
    participant DB as PRRepository
    participant Git as GitWorkflowManager

    User->>CLI: codeframe work start --create-branch
    CLI->>Git: create_feature_branch()
    Git->>DB: store branch association
    Git-->>CLI: branch created
    CLI-->>User: Branch created, task started

    User->>CLI: codeframe pr create --auto-description
    CLI->>Git: get current branch & diff
    CLI->>DB: fetch related tasks
    CLI->>AI: generate_description(changes, context)
    AI-->>CLI: title + description
    CLI->>GH: create_pull_request()
    GH-->>CLI: PR details
    CLI->>DB: store PR record
    CLI-->>User: PR created with URL

    User->>CLI: codeframe pr merge <number>
    CLI->>DB: get PR details
    CLI->>CLI: run_pr_gates()
    CLI-->>User: display gate results
    User->>CLI: confirm merge
    CLI->>GH: merge_pull_request()
    GH-->>CLI: merge result
    CLI->>DB: update PR status
    CLI-->>User: PR merged successfully
```

### Configuration Requirements

**Environment Variables** (add to file:.env.example):
```
# GitHub Integration
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
GITHUB_REPO=owner/repo-name

# PR Workflow Settings (optional)
PR_DEFAULT_BASE=main
PR_AUTO_DELETE_BRANCH=false
PR_REQUIRE_GATES=true
```

**Project Config** (extend file:codeframe/core/config.py):
```python
class PRWorkflowConfig(BaseModel):
    default_base_branch: str = "main"
    auto_delete_merged_branches: bool = False
    require_gates_before_merge: bool = True
    default_merge_strategy: str = "squash"
    enable_ai_descriptions: bool = True
```

### Error Handling Strategy

**Common Error Scenarios:**

1. **GitHub Not Configured**: Display helpful message with setup instructions
2. **Branch Not Found**: Suggest creating branch or checking branch name
3. **PR Already Exists**: Show existing PR URL
4. **Merge Conflicts**: Display conflict files, suggest resolution steps
5. **Gate Failures**: Show detailed failure reasons, allow override
6. **API Rate Limits**: Implement retry with exponential backoff
7. **Network Errors**: Graceful degradation, cache locally

### Key Files Summary

**New Files:**
- file:codeframe/cli/pr_commands.py - PR CLI commands
- file:codeframe/cli/work_commands.py - Work/task CLI commands
- file:codeframe/lib/pr_description_generator.py - AI description generation
- file:tests/cli/test_pr_commands.py - PR command tests
- file:tests/cli/test_work_commands.py - Work command tests
- file:docs/PR_WORKFLOW.md - PR workflow documentation

**Modified Files:**
- file:codeframe/cli/__init__.py - Register new command groups
- file:codeframe/core/config.py - Add PR workflow configuration
- file:codeframe/git/workflow_manager.py - Enhance branch management
- file:docs/CLI_WIREFRAME.md - Document new commands
- file:.env.example - Add GitHub configuration examples

---

Execution Information

Branch: main
Commit: 81fdeee

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

Warning

Something went wrong while processing your request.

Reference ID: 493706a5-a2b1-4114-a21d-fe8b78ac8cdf

Please try again or contact support if the issue persists, referencing this ID.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#1 - Add Claude Code GitHub Workflow [merged]
#35 - fix: Resolve E2E test timeout failures in GitHub Actions [merged]
#95 - feat(ci): Add deployment workflow for staging and production [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#241 - feat(ui): add phase-awareness to AgentList, QualityGatesPanel, and CostDashboard [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!