# Upgrade Hpp

> `/upgrade-hpp` — Automate HPP Version Upgrade to Esperanto

- Skill: `valasubramanian-kr/upgrade-hpp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add valasubramanian-kr/upgrade-hpp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/valasubramanian-kr/upgrade-hpp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: valasubramanian-kr (https://skillmd.com/u/valasubramanian-kr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/valasubramanian-kr/upgrade-hpp

---


# `/upgrade-hpp` — Automate HPP Version Upgrade to Esperanto

## Purpose

Automates the workflow of upgrading a Hosted Payment Page (HPP) review version in the Esperanto repository. When an HPP PR with label 'qa:required' is created, a review version is published (e.g., "3.0.96-3287898"). This skill extracts that version from the PR comments and creates an upgrade PR in Esperanto automatically.

**What it does**:
1. Auto-detects current repo (HPP or Esperanto)
2. Gets HPP PR number (from current branch or user argument)
3. Fetches HPP PR details (branch name and title)
4. Fetches HPP PR comments and extracts review version
5. Creates upgrade branch in Esperanto repo **using HPP PR's branch name**
6. Runs `update_whpp_version.sh` script to update package.json files
7. Commits, pushes, and creates Esperanto PR with **HPP PR title + " | QA Reviewer App"**
8. Uses Esperanto's predefined PR template (no custom body)

**Type**: Standalone coordinator (spawns general-purpose sub-agent)

---

## Usage

### From HPP Repo (Auto-detect PR)

```bash
# On HPP PR branch with review version comment
cd /Users/thw6774/Documents/repos/hosted-payment-page
git checkout <HPP-PR-branch>
/upgrade-hpp
```

### From HPP Repo (Explicit PR Number)

```bash
cd /Users/thw6774/Documents/repos/hosted-payment-page
/upgrade-hpp 296
```

### From Esperanto Repo (Requires PR Number)

```bash
cd /Users/thw6774/Documents/repos/esperanto
/upgrade-hpp 296
```

---

## Prerequisites

**Required**:
- GitHub MCP server configured (for PR comment fetching and creation)
- `gh` CLI authenticated (for PR operations)
- HPP and Esperanto repos cloned as siblings in `/Users/thw6774/Documents/repos/`
- HPP PR must have comment matching: "A review version has been published: X.Y.Z-COMMIT"

**Validation**:
```bash
# Check GitHub MCP
grep -q "github" ~/.mcp.json || echo "❌ GitHub MCP not configured"

# Check gh CLI
gh auth status || echo "❌ gh CLI not authenticated"

# Check repo structure
ls -d /Users/thw6774/Documents/repos/{hosted-payment-page,esperanto} || echo "❌ Repos not found"
```

---

## Instructions

You are the **coordinator** for the `/upgrade-hpp` skill. Follow the coordinator-agent pattern:
1. Validate prerequisites
2. Detect execution context
3. Get HPP PR number
4. Spawn sub-agent to execute upgrade
5. Report results to user
6. **NEVER retry sub-agent work** - report failures to user

### Step 1: Validate Prerequisites

Check required tools and access:

```bash
# Validate GitHub MCP (check if mcp__github tools are available)
# If not available: ERROR "GitHub MCP not configured. See .mcp.json"

# Validate gh CLI
if ! command -v gh &> /dev/null; then
  echo "❌ gh CLI not found. Install: brew install gh"
  exit 1
fi

# Check gh auth
if ! gh auth status &> /dev/null; then
  echo "❌ gh CLI not authenticated. Run: gh auth login"
  exit 1
fi
```

### Step 2: Detect Repo Context

Determine if running from HPP or Esperanto repo:

```bash
# Get current repo from git remote
REMOTE_URL=$(git remote get-url origin 2>/dev/null)

if [ -z "$REMOTE_URL" ]; then
  echo "❌ Not in a git repository"
  exit 1
fi

# Extract repo slug
REPO_SLUG=$(echo "$REMOTE_URL" | sed 's/.*[:/]\([^/]*\/[^/]*\)\.git/\1/' | sed 's/.*[:/]\([^/]*\/[^/]*\)$/\1/')

case "$REPO_SLUG" in
  "krogertechnology/hosted-payment-page")
    CURRENT_REPO="HPP"
    echo "Detected: Hosted Payment Page repo"
    ;;
  "krogertechnology/esperanto")
    CURRENT_REPO="ESPERANTO"
    echo "Detected: Esperanto repo"
    ;;
  *)
    echo "❌ Unknown repo: $REPO_SLUG"
    echo "Must run from HPP or Esperanto repo"
    exit 1
    ;;
esac
```

### Step 3: Get HPP PR Number

Extract PR number from current branch or user argument:

```bash
# Check if user provided PR number as argument
if [ -n "$1" ]; then
  PR_NUMBER="$1"
  echo "Using provided HPP PR number: $PR_NUMBER"
else
  # Try auto-detect if in HPP repo
  if [ "$CURRENT_REPO" = "HPP" ]; then
    PR_NUMBER=$(gh pr view --json number -q .number 2>/dev/null)

    if [ -z "$PR_NUMBER" ]; then
      # Not on a PR branch - ask user
      # Use AskUserQuestion to get PR number
      echo "❌ Not on HPP PR branch and no PR number provided"
      echo "Usage: /upgrade-hpp <HPP-PR-NUMBER>"
      exit 1
    fi

    echo "Auto-detected HPP PR: #$PR_NUMBER"
  else
    # In Esperanto repo - require argument
    echo "❌ HPP PR number required when running from Esperanto repo"
    echo "Usage: /upgrade-hpp <HPP-PR-NUMBER>"
    exit 1
  fi
fi

# Validate PR number is numeric
if ! [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
  echo "❌ Invalid PR number: $PR_NUMBER (must be numeric)"
  exit 1
fi
```

### Step 4: Determine Esperanto Repo Path

Find Esperanto repo location:

```bash
if [ "$CURRENT_REPO" = "HPP" ]; then
  # We're in HPP - find sibling Esperanto repo
  HPP_PATH=$(pwd)
  PARENT_DIR=$(dirname "$HPP_PATH")
  ESPERANTO_PATH="${PARENT_DIR}/esperanto"

  if [ ! -d "$ESPERANTO_PATH/.git" ]; then
    # Esperanto repo not found as sibling - ask user
    # Use AskUserQuestion to get Esperanto path
    echo "❌ Esperanto repo not found at: $ESPERANTO_PATH"
    echo "Expected repos to be siblings in: $PARENT_DIR"
    exit 1
  fi

  echo "Found Esperanto repo: $ESPERANTO_PATH"
else
  # We're already in Esperanto
  ESPERANTO_PATH=$(pwd)
  echo "Using current Esperanto repo: $ESPERANTO_PATH"
fi
```

### Step 5: Spawn Upgrade Sub-Agent

Use the `Task` tool to spawn a general-purpose sub-agent that executes the upgrade workflow:

**Task Configuration**:
```
subagent_type: "general-purpose"
description: "Upgrade HPP version in Esperanto"
model: "sonnet"  # Complex workflow with multiple git operations
```

**Sub-Agent Prompt**:

```markdown
Upgrade Hosted Payment Page version in Esperanto repo from HPP PR review version.

## CONTEXT

- **HPP PR Number**: <PR_NUMBER>
- **Current Repo**: <CURRENT_REPO>
- **Esperanto Path**: <ESPERANTO_PATH>
- **HPP Repo**: krogertechnology/hosted-payment-page
- **Esperanto Repo**: krogertechnology/esperanto

## TASKS

Execute the following tasks in sequence. On ANY error, stop immediately and report the failure.

### Task 1: Fetch HPP PR Details

Use `mcp__github__pull_request_read` to get PR details:

```
owner: "krogertechnology"
repo: "hosted-payment-page"
pullNumber: <PR_NUMBER>
method: "get"
```

Extract from the response:
- **Branch name** (head.ref): The source branch name of the HPP PR
- **PR title**: The title of the HPP PR

Store these for later use:
- HPP_BRANCH_NAME
- HPP_PR_TITLE

### Task 2: Fetch HPP PR Comments

Use `mcp__github__pull_request_read` to get PR comments:

```
owner: "krogertechnology"
repo: "hosted-payment-page"
pullNumber: <PR_NUMBER>
method: "get_comments"
```

### Task 3: Extract Review Version

Search comments for version pattern:
- **Pattern**: `A review version has been published: (\d+\.\d+\.\d+-[a-f0-9]+)`
- **Example**: "A review version has been published: 3.0.96-3287898"
- Extract the version string (e.g., "3.0.96-3287898")

**Error Handling**:
- If no match found: ERROR "No review version comment found in HPP PR #<PR_NUMBER>. Ensure PR has 'qa:required' label and version has been published."
- If multiple matches: Use the MOST RECENT comment (last in list)

### Task 4: Check for Existing Upgrade PR

Check if upgrade PR already exists in Esperanto using the HPP branch name:

```bash
gh pr list --head "<HPP_BRANCH_NAME>" --repo krogertechnology/esperanto --json number,title,state
```

**Error Handling**:
- If open PR found: Ask user via `AskUserQuestion`:
  - Question: "An upgrade PR already exists for HPP #<PR_NUMBER>. What would you like to do?"
  - Options:
    1. "Update existing PR" → Close existing and create new
    2. "Skip and exit" → Exit successfully with message
    3. "Create new anyway" → Continue with new PR
- If closed PR found: Continue (create new PR)

### Task 5: Create Upgrade Branch in Esperanto

```bash
cd <ESPERANTO_PATH>

# Ensure on main and up to date
git fetch origin
git checkout main
git pull origin main

# Create upgrade branch using HPP PR's branch name
BRANCH="<HPP_BRANCH_NAME>"
git checkout -b "$BRANCH"

echo "Created branch: $BRANCH"
```

**Branch naming**: Use the same branch name as the HPP PR's head branch
- Example: If HPP PR branch is `dcppay-296-add-feature`, Esperanto branch will be `dcppay-296-add-feature`

### Task 6: Run Update Script

Navigate to script directory and execute:

```bash
cd <ESPERANTO_PATH>/@kroger/buy/kroger-hosted-payment-page/scripts

# Run update script with version
./update_whpp_version.sh "<VERSION>"
SCRIPT_EXIT=$?

if [ $SCRIPT_EXIT -ne 0 ]; then
  echo "❌ Script failed with exit code: $SCRIPT_EXIT"
  exit 1
fi

echo "✓ Script completed successfully"
```

**Expected Changes**:
- 3 package.json files should be modified:
  1. `@kroger/buy/kroger-hosted-payment-page/package.json`
  2. `package.json` (root)
  3. `@kroger/health/pharmacy/package.json`

### Task 7: Verify Changes

```bash
cd <ESPERANTO_PATH>

# Check git status
CHANGED_FILES=$(git status --porcelain | wc -l)

if [ $CHANGED_FILES -eq 0 ]; then
  echo "❌ No files changed after script execution"
  exit 1
fi

# Verify expected files are modified
git diff --name-only | grep -E "(package\.json|package-lock\.json|yarn\.lock)" || {
  echo "❌ Unexpected file changes. Expected package.json modifications."
  git status
  exit 1
}

echo "✓ Verified expected file changes"
```

### Task 8: Commit Changes

```bash
cd <ESPERANTO_PATH>

# Stage all package files
git add -A

# Create commit message
COMMIT_MSG="chore: upgrade hosted-payment-page to <VERSION>

Automated upgrade from HPP PR #<PR_NUMBER>
Review version published: <VERSION>

Refs: HPP-<PR_NUMBER>
"

git commit -m "$COMMIT_MSG"

echo "✓ Committed changes"
```

### Task 9: Push Branch

```bash
git push -u origin "$BRANCH"

echo "✓ Pushed branch: $BRANCH"
```

### Task 10: Create Esperanto PR

Use `mcp__github__create_pull_request`:

```
owner: "krogertechnology"
repo: "esperanto"
head: <BRANCH>
base: "main"
title: "<HPP_PR_TITLE> | QA Reviewer App"
draft: false
```

**Important**:
- **Title**: Use the HPP PR title exactly, then append " | QA Reviewer App"
  - Example: If HPP title is "Add card validation", Esperanto title is "Add card validation | QA Reviewer App"
- **Body**: Do NOT provide a body parameter - let Esperanto use its predefined PR template markdown

**Add Labels**:

After PR creation, add labels using `gh` CLI:

```bash
gh pr edit <PR_NUMBER> --repo krogertechnology/esperanto \
  --add-label "version-minor" \
  --add-label "Autodeploy Stage Review App"
```

### Task 11: Report Success

Display results in table format:

```
✓ HPP Upgrade Complete

| Field | Value |
|-------|-------|
| Esperanto PR | #<ESPERANTO_PR_NUMBER> |
| HPP Source PR | #<HPP_PR_NUMBER> |
| HPP PR Title | <HPP_PR_TITLE> |
| Esperanto PR Title | <HPP_PR_TITLE> | QA Reviewer App |
| Version | <VERSION> |
| Branch | <HPP_BRANCH_NAME> |
| Labels | version-minor, Autodeploy Stage Review App |

URL: <ESPERANTO_PR_URL>

Next: Monitor CI/CD checks in Esperanto PR for autodeploy to stage
```

## ERROR HANDLING

**Critical Errors** (stop immediately):
- No review version comment found
- Script execution fails
- Git operations fail
- PR creation fails
- GitHub authentication fails

**User Input Errors** (ask for clarification):
- Esperanto repo not found at expected path
- Existing upgrade PR found
- Not on HPP PR branch (when auto-detecting)

**All errors must**:
- Log to stderr with clear error message
- Provide recovery steps
- Exit immediately (no retry)
```

### Step 6: Report Results

After sub-agent completes:

**On Success**:
- Display sub-agent's success message (includes PR details table)
- Do NOT summarize or add commentary
- Let user know next steps are in the message

**On Failure**:
- Display sub-agent's error message exactly
- Provide recovery guidance:
  - Missing version comment → Check HPP PR has 'qa:required' label
  - Script failure → Verify Esperanto repo state
  - Auth failure → Check GitHub MCP and gh CLI auth
  - Existing PR → User decides via AskUserQuestion
- **NEVER retry the sub-agent work yourself**

**Example Success Output**:
```
✓ HPP Upgrade Complete

| Field | Value |
|-------|-------|
| Esperanto PR | #789 |
| HPP Source PR | #296 |
| HPP PR Title | Add card validation |
| Esperanto PR Title | Add card validation | QA Reviewer App |
| Version | 3.0.96-3287898 |
| Branch | dcppay-296-add-card-validation |
| Labels | version-minor, Autodeploy Stage Review App |

URL: https://github.com/krogertechnology/esperanto/pull/789

Next: Monitor CI/CD checks in Esperanto PR for autodeploy to stage
```

---

## Verification

After skill execution, verify:

```bash
# 1. Branch exists in Esperanto (should match HPP PR branch name)
cd /Users/thw6774/Documents/repos/esperanto
git branch --list "dcppay-*"

# 2. Package.json files updated
grep "@kroger/hosted-payment-page" @kroger/buy/kroger-hosted-payment-page/package.json
grep "@kroger/hosted-payment-page" package.json
grep "@kroger/hosted-payment-page" @kroger/health/pharmacy/package.json

# 3. PR created with correct labels
gh pr view <PR-NUMBER> --repo krogertechnology/esperanto --json labels,title,body

# 4. Verify labels
gh pr view <PR-NUMBER> --repo krogertechnology/esperanto --json labels -q '.labels[].name'
```

---

## Security

**Safe Operations**:
- Read-only access to HPP PR (fetch comments only)
- Creates new branch (non-destructive)
- No force-push or destructive git operations
- Version string validated before script execution

**Validation**:
- Version format: `\d+\.\d+\.\d+-[a-f0-9]+`
- PR number: numeric only
- Script path: verify exists before execution

**No Secrets**:
- GitHub auth via MCP/gh CLI
- No API tokens in skill code
- No PII or sensitive data

---

## Related Files

| File | Purpose |
|------|---------|
| context/repos/esperanto.md | PR template, branch naming |
| context/repos/hosted-payment-page.md | HPP repo identity |
| skills/push/SKILL.md | GitHub MCP PR creation pattern |
| skills/pull/SKILL.md | Repo detection pattern |
| skills/branch/SKILL.md | Branch creation pattern |