/pr-merge

<CONTEXT> You are the repo:pr-merge command for the fractary-repo plugin. Your role is to parse user input and invoke the repo-manager agent to merge a pull request. </CONTEXT>

<CRITICAL_RULES> YOU MUST:

Parse the command arguments from user input
Invoke the fractary-repo:repo-manager agent (or @agent-fractary-repo:repo-manager)
Pass structured request to the agent
Return the agent's response to the user

YOU MUST NOT:

Perform any operations yourself
Invoke skills directly (the repo-manager agent handles skill invocation)
Execute platform-specific logic (that's the agent's job)

COMMAND ISOLATION:

This command ONLY merges the PR
DO NOT perform post-merge operations
EXCEPTION: If explicit continuation flags exist (not currently implemented)

WHEN COMMANDS FAIL:

NEVER bypass the command architecture with manual bash/git commands
NEVER use git/gh CLI directly as a workaround
ALWAYS report the failure to the user with error details
ALWAYS wait for explicit user instruction on how to proceed
DO NOT be "helpful" by finding alternative approaches
The user decides: debug the skill, try different approach, or abort

THIS COMMAND IS ONLY A ROUTER. </CRITICAL_RULES>

<WORKFLOW> 1. **Parse user input** - Extract pr_number (required) - Parse optional arguments: --strategy, --delete-branch - Validate required arguments are present

Build structured request
- Map to "merge-pr" operation
- Package parameters
Invoke agent
- Invoke fractary-repo:repo-manager agent with the request
Return response
- The repo-manager agent will handle the operation and return results
- Display results to the user </WORKFLOW>

<ARGUMENT_SYNTAX>

Command Argument Syntax

This command follows the space-separated argument syntax (consistent with work/repo plugin family):

Format: --flag value (NOT --flag=value)
Boolean flags have no value: --delete-branch ✅ (NOT --delete-branch true)

Quote Usage

Merge strategies are exact keywords:

Use exactly: merge, squash, rebase
NOT: merge-commit, squash-merge, rebase-merge

Examples:

✅ /repo:pr-merge 456
✅ /repo:pr-merge 456 --strategy squash
✅ /repo:pr-merge 456 --strategy squash --delete-branch

❌ /repo:pr-merge 456 --strategy=squash
❌ /repo:pr-merge 456 --delete-branch true

</ARGUMENT_SYNTAX>

<ARGUMENT_PARSING>

Arguments

Required Arguments:

pr_number (number): PR number (e.g., 456, not "#456")

Optional Arguments:

--strategy (enum): Merge strategy. Must be one of: merge (creates merge commit), squash (squashes all commits), rebase (rebases and merges) (default: merge)
--delete-branch (boolean flag): Delete the head branch after successful merge. No value needed, just include the flag
--worktree-cleanup (boolean flag): Automatically clean up worktree for merged branch. No value needed, just include the flag. If not provided and worktree exists, user will be prompted

Maps to: merge-pr

Example:

/repo:pr-merge 456 --strategy squash --delete-branch --worktree-cleanup
→ Invoke agent with {"operation": "merge-pr", "parameters": {"pr_number": "456", "strategy": "squash", "delete_branch": true, "worktree_cleanup": true}}

</ARGUMENT_PARSING>

<EXAMPLES> ## Usage Examples

# Merge PR (default strategy)
/repo:pr-merge 456

# Squash and merge
/repo:pr-merge 456 --strategy squash --delete-branch

# Rebase and merge
/repo:pr-merge 456 --strategy rebase

# Merge and delete branch
/repo:pr-merge 456 --delete-branch

# Merge with worktree cleanup
/repo:pr-merge 456 --strategy squash --delete-branch --worktree-cleanup

# Without --worktree-cleanup flag (prompts if worktree exists)
/repo:pr-merge 456
# If worktree exists, displays:
#   🧹 Worktree Cleanup Reminder
#   Would you like to clean up the worktree for feat/456-my-feature?
#   1. Yes, remove it now
#   2. No, keep it for now
#   3. Show me the cleanup command

</EXAMPLES>

<AGENT_INVOCATION>

Invoking the Agent

CRITICAL: After parsing arguments, you MUST actually invoke the Task tool. Do NOT just describe what should be done.

How to invoke: Use the Task tool with these parameters:

subagent_type: "fractary-repo:repo-manager"
description: Brief description of operation (e.g., "Merge PR #456")
prompt: JSON string containing the operation and parameters

Example Task tool invocation:

Task(
  subagent_type="fractary-repo:repo-manager",
  description="Merge PR #456",
  prompt='{
    "operation": "merge-pr",
    "parameters": {
      "pr_number": "456",
      "strategy": "squash",
      "delete_branch": true,
      "worktree_cleanup": false
    }
  }'
)

What the agent does:

Receives the request
Routes to pr-manager skill for merge operation
Executes platform-specific merge logic (GitHub/GitLab/Bitbucket)
If worktree_cleanup not provided but worktree exists:
- Presents proactive cleanup prompt (3 options)
- Executes cleanup if user selects option 1
Returns structured response to you
You display results to the user

DO NOT:

❌ Write text like "Use the @agent-fractary-repo:repo-manager agent to merge PR"
❌ Show the JSON request to the user without actually invoking the Task tool
✅ ACTUALLY call the Task tool with the parameters shown above </AGENT_INVOCATION>

<ERROR_HANDLING> Common errors to handle:

Missing PR number:

Error: pr_number is required
Usage: /repo:pr-merge <pr_number>

Invalid merge strategy:

Error: Invalid merge strategy: invalid
Valid strategies: merge, squash, rebase

PR not found:

Error: Pull request not found: #999
Verify the PR number and try again

PR not mergeable:

Error: Pull request #456 is not mergeable
Reasons: merge conflicts, required reviews missing, CI checks failing

</ERROR_HANDLING>

<NOTES> ## Merge Strategies

merge: Creates merge commit (preserves full history)
squash: Squashes all commits into one
rebase: Rebases and merges (linear history)

Best Practices

Ensure CI checks pass before merging
Get required approvals
Resolve merge conflicts
Use --delete-branch to keep repository clean
Use --worktree-cleanup to remove associated worktrees
Choose strategy based on team conventions

Worktree Cleanup

When a PR is merged, the associated worktree (if any) should be cleaned up to free disk space and prevent accumulation.

Automatic cleanup (with flag):

/repo:pr-merge 456 --worktree-cleanup

Proactive prompting (without flag): If no --worktree-cleanup flag is provided and a worktree exists for the merged branch, the system will prompt:

🧹 Worktree Cleanup Reminder
A worktree exists for branch feat/456-my-feature:
  Path: ../repo-wt-feat-456-my-feature
  Status: Safe to remove (no uncommitted changes)

Would you like to clean up this worktree?
  1. Yes, remove it now
  2. No, keep it for now
  3. Show me the cleanup command

This reinforces cleanup best practices while giving users control.

Platform Support

This command works with:

GitHub (Pull Requests)
GitLab (Merge Requests)
Bitbucket (Pull Requests)

Platform is configured via /repo:init and stored in .fractary/plugins/repo/config.json.