version: "1.0.0"

WSO2 Porting Skill

The WSO2 Porting Skill is a agent-independent skill definition.

Architecture

flowchart TD
    A[User Invocation] --> B{Input Form?}
    B -->|PR Number| C[Resolve Merge Commit]
    B -->|Merge Commit| D[Resolve PR Number]
    C --> E[Extract Feature Commit]
    D --> E
    E --> F[Create Isolated Worktree]
    F --> G[Fetch PR & Issue Context]
    G --> H[Attempt Cherry-Pick]
    H -->|Success| I[Compile & Verify]
    H -->|Conflict| J[Abort Cherry-Pick]
    J --> K[Contextual Analysis]
    K --> L[Manual Surgical Port]
    L --> I
    I -->|Failed| M{Retry < 3?}
    M -->|Yes| N[Analyze Error]
    N --> O[Apply Fix]
    O --> I
    M -->|No| P[Report Failure]
    I -->|Success| Q[Commit Locally]
    Q --> R[Print Summary]

Compatibility

How It Works

Dual Input Modes

The skill accepts two natural language invocation patterns:

Form A - By PR Number:

Port PR #456 to release-4.3.x using wso2-porting-skill

• Extracts: PR_NUMBER, TARGET_BRANCH
• Resolves: MERGE_COMMIT from git log

Form B - By Merge Commit:

Port PR in merge commit abc123def to release-4.3.x using wso2-porting-skill

• Extracts: MERGE_COMMIT, TARGET_BRANCH
• Resolves: PR_NUMBER from commit message or MCP

Installation

Prerequisites

• Git
• Java 21 and Maven 3.x
• One of: Claude Code, GitHub Copilot, or Codex CLI
• GitHub Personal Access Token for MCP server (Not needed for copilot)

For Claude Code

1. Create agent directory:

``bash mkdir -p .claude/agents ``

1. Copy skill file:

``bash cp porting-skill/wso2-porting-skill .claude/agents/ ``

1. Configure GitHub MCP:

``bash claude mcp add --transport http github \ https://api.githubcopilot.com/mcp \ -H "Authorization: Bearer YOUR_GITHUB_PAT" ``

1. Verify installation:

``bash claude mcp list # Should show 'github' server ``

For GitHub Copilot

1. Create skills directory:

``bash mkdir -p .github/skills ``

1. Copy skill file:

``bash cp porting-skill/wso2-porting-skill .github/skills/ ``

1. Commit skill file:

``bash git add .github/skills/ git commit -m "Add WSO2 porting skill" git push ``

For Codex CLI

1. Create Codex directory:

``bash mkdir -p .codex ``

1. Copy skill file:

``bash cp porting-skill/wso2-porting-skill .codex/ ``

1. Configure MCP in `~/.codex/config.toml`:

```toml [mcp_servers.github] command = "npx" args = ["-y", "@modelcontextprotocol/server-github"] enabled = true

[mcp_servers.github.env] GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" ```

1. Set environment variable:

``bash export GITHUB_TOKEN="your_github_pat_here" # Add to ~/.bashrc or ~/.zshrc for persistence ``

[!NOTE]

Codex CLI may experience intermittent MCP connectivity issues. The skill includes automatic curl fallback for robustness.

Usage

Basic Invocation

Simply use natural language in your coding assistant:

By PR number:

Port PR #789 to feature-governance using wso2-porting-skill

By merge commit:

Port PR in merge commit a1b2c3d4 to release-4.2.x using wso2-porting-skill

What Happens

The skill runs fully autonomously and:

1. Resolves the feature commit from merge commit
2. Fetches PR and linked issue details
3. Creates isolated worktree
4. Attempts cherry-pick or performs manual port
5. Builds and verifies with Maven (up to 3 retries)
6. Commits changes locally
7. Prints summary with worktree location

Expected Output

On success, you'll see:

Port complete
Branch:   port/789-to-feature-governance
Worktree: /path/to/porting-feature-governance-1234567890
 
What was done:
- Cherry-pick succeeded cleanly
- Build passed on first attempt
- No architectural adaptations needed
 
To push and open a PR, run:
  cd /path/to/porting-feature-governance-1234567890
  git push -u origin port/789-to-feature-governance

On failure:

Porting not possible after 3 build attempts.
 
PR:     #789 -> feature-governance
Reason: [ERROR] package com.example.newfeature does not exist
Files changed: src/main/java/com/example/Feature.java, pom.xml
Suggested next step: Target branch missing dependency - check if 
                     com.example.newfeature is available in feature-governance

How the Skill Works

1. Feature Commit Resolution

The skill never uses merge commits directly for diffs:

# Merge commits have two parents - we need the feature branch parent
FEATURE_COMMIT=$(git log --merges -1 --pretty="%P" $MERGE_COMMIT | awk '{print $2}')

This ensures clean, accurate diffs without merge artifacts.

2. Worktree Isolation

Every port uses an isolated worktree:

WORKTREE_DIR="$(cd .. && pwd)/porting-${TARGET_BRANCH}-${TIMESTAMP}"
git worktree add -b "port/${PR_ID}-to-${TARGET_BRANCH}" $WORKTREE_DIR $TARGET_BRANCH

Benefits:

• No interference with main repository
• Multiple ports can run simultaneously
• Easy cleanup on failure
• Preserves git state

[!IMPORTANT]

The skill explicitly re-enters the worktree with cd $WORKTREE_DIR in every command block to handle shell context resets between tool calls.

3. Context Fetching

Primary: GitHub MCP Server

// Uses MCP tools
get_pull_request(repo, pr_number)
get_issue(repo, issue_number)

Fallback: curl + GitHub API

# If MCP unavailable or fails
curl -H "Authorization: Bearer ${GITHUB_TOKEN}" \
  "https://api.github.com/repos/${REPO}/pulls/${PR_NUMBER}"

Last Resort: Unauthenticated

# For public repos only (60 req/hr limit)
curl "https://api.github.com/repos/${REPO}/pulls/${PR_NUMBER}"

4. Smart Porting Strategy

graph TD
    A[Cherry-pick attempt] --> B{Exit code?}
    B -->|0 - Success| C[Skip to build]
    B -->|Non-zero| D[Abort cherry-pick]
    D --> E[Get changed files list]
    E --> F[Read source versions from git history]
    F --> G[Analyze target architecture]
    G --> H[Edit ONLY changed files]
    H --> I[Match target patterns]
    I --> C[Build & verify]

Manual porting rules:

• Edit only files in git show $FEATURE_COMMIT --name-only
• Read source from git show $FEATURE_COMMIT:<path>
• Achieve same logical outcome, not literal copy
• Use PR/issue context to understand intent
• For pom.xml: add only missing <dependency> blocks

5. Self-Healing Build Loop

flowchart LR
    A[Build] --> B{Success?}
    B -->|Yes| C[Commit]
    B -->|No| D{Attempt < 3?}
    D -->|Yes| E[Strategy]
    E -->|Attempt 2| F[Fix first ERROR line]
    E -->|Attempt 3| G[Check dependency tree]
    E -->|Attempt 4| H[Stop - report failure]
    F --> A
    G --> A
    D -->|No| H

Retry strategies:

• Attempt 2: Find first ERROR line, fix only that
• Attempt 3: Run mvn dependency:tree to check for missing/conflicting dependencies
• Attempt 4: Stop. Report exact error and suggest next steps

Build Configuration

Initial Build

mvn clean install --ntp -T 1C \
  -Dcheckstyle.skip=true \
  -Dmaven.javadoc.skip=true \
  -Dmaven.test.skip=true

Flags:

• --ntp: No transfer progress (cleaner logs, still shows errors)
• -T 1C: Parallel builds (1 thread per CPU core)
• Skip checkstyle, javadoc, tests for speed

Retry Builds

mvn install --ntp -T 1C \
  -Dcheckstyle.skip=true \
  -Dmaven.javadoc.skip=true \
  -Dmaven.test.skip=true

Why not `clean`: Dependencies already downloaded, just need to recompile/reinstall.

Troubleshooting Hangs

If no output for 5+ minutes:

# Kill the build process, then:
mvn dependency:resolve

This diagnoses network or repository issues.

Troubleshooting

Skill Not Recognized

Issue: Coding assistant doesn't recognize the skill

Solutions:

• Claude Code: Verify file is in .claude/agents/ and restart Claude
• GitHub Copilot: Ensure file is in .github/skills/ and committed to repo
• Codex CLI: Check file is in .codex/ or .github/
• Try invoking with exact skill name: using wso2-porting-skill

MCP Connection Failed

Issue: Cannot fetch PR/issue details

Solutions:

• Verify GitHub PAT is valid and not expired
• Check MCP server configuration
• Test MCP independently: claude mcp test github (Claude Code)
• Skill automatically falls back to curl - check GITHUB_TOKEN env var

Worktree Creation Failed

Issue: git worktree add fails

Solutions:

• Check if branch name already exists: git branch -D port/<pr>-to-<branch>
• Verify target branch exists: git branch -a | grep <target>
• Clean up stale worktrees: git worktree prune
• Ensure path doesn't exist: remove ../porting-* directories

Cherry-Pick Failed, Manual Port Failed

Issue: Both automatic and manual porting fail

Solutions:

• Check if files were moved/renamed in target branch: find . -name "*<filename>*"
• Verify dependencies exist: compare pom.xml between source and target
• Review structural differences: source may use patterns not in target
• Consider if feature requires target branch to evolve first

Build Succeeds Locally, Fails in Skill

Issue: Manual build works, but skill build fails

Solutions:

• Verify skill is using correct worktree path
• Check Java version: skill assumes Java 21
• Ensure Maven settings.xml is accessible
• Review if builds depend on local state not in git

Advanced Usage

Customizing the Skill

Edit SKILL.md to modify behavior:

Change build commands:

## 7. Compile and verify
mvn verify -Pintegration-tests  # Run integration tests

Add pre-port validation:

## 3.5. Validate target branch
cd $WORKTREE_DIR && ./scripts/validate-compatibility.sh

Modify retry strategy:

**Attempt 2:** Run `mvn dependency:resolve` first, then rebuild
**Attempt 3:** Run `mvn clean` to force full rebuild

Cleanup

Remove Worktrees

After pushing (or on failure):

# List worktrees
git worktree list
 
# Remove specific worktree
git worktree remove ../porting-feature-governance-1234567890
 
# Prune stale worktree references
git worktree prune

Delete Port Branches

After PRs are merged or abandoned:

# Delete local branch
git branch -D port/789-to-feature-governance
 
# Delete remote branch
git push origin --delete port/789-to-feature-governance

Best Practices

1. Clear PR Descriptions: Link to issues and explain the "why" for better AI context
2. Descriptive Issue Context: AI uses issue descriptions to understand intent
3. Review Before Push: The skill commits locally - always review before pushing
4. Incremental Porting: Start with simple PRs to verify skill works in your environment
5. Keep Skill Updated: Pull latest version for bug fixes and improvements
6. Monitor Worktrees: Clean up old worktrees regularly to save disk space

Limitations

• MCP connectivity can be flaky (curl fallback helps)
• Best results with PRs that have clear issue descriptions

Further Reading

• Git Worktree Documentation
• Model Context Protocol (MCP)
• Claude Code Agent Documentation
• GitHub Copilot Skills