# Auto Deploy Esperanto Review App

> `/auto-deploy-esperanto-review-app` — Automate Esperanto Review App Deployment

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

---


# `/auto-deploy-esperanto-review-app` — Automate Esperanto Review App Deployment

## Purpose

Automates the deployment of HPP review versions to Esperanto QA stage environment. When an HPP PR with label 'qa-required' publishes a review version (e.g., "3.0.130-074e20d"), this skill extracts that version and creates/updates an Esperanto PR for QA testing.

**What it does**:
1. Auto-detects current HPP PR (from branch or user argument)
2. Fetches HPP PR details (branch name, title, and labels)
3. Validates PR has 'qa-required' label
4. Extracts review version from PR comments
5. Checks out Esperanto repository
6. Creates/updates branch in Esperanto **using HPP PR's branch name**
7. Updates `package.json` with `yarn add @kroger/hosted-payment-page@VERSION`
8. Commits and pushes changes
9. Creates new Esperanto PR with **"[Payments] " + HPP PR title** OR updates existing PR
10. Adds labels: "Autodeploy Stage Review App", "version-minor"
11. Comments back on HPP PR with Esperanto PR link

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

---

## Usage

### From HPP Repo

```bash
# Provide the HPP PR number as argument
cd <path-to-hosted-payment-page-repo>
/auto-deploy-esperanto-review-app <PR-NUMBER>

# Example:
/auto-deploy-esperanto-review-app 328
```

**Note**: PR number is required. You can find it in the PR URL or by running `git branch --show-current` and checking GitHub.

---

## Prerequisites

**Required**:
- GitHub MCP server configured (for PR operations)
- `yarn` installed (for package updates)
- HPP and Esperanto repos cloned as sibling directories (same parent folder)
- HPP PR must have:
  - Label: 'qa-required'
  - Comment matching: "A review version has been published: X.Y.Z-COMMIT"

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

# Check yarn
command -v yarn || echo "❌ yarn not installed"

# Verify we're in HPP repo
git remote get-url origin | grep -q "hosted-payment-page" || echo "❌ Not in HPP repo"
```

---

## Instructions

You are the **coordinator** for the `/auto-deploy-esperanto-review-app` skill. Follow the coordinator-agent pattern:
1. Validate prerequisites
2. Get HPP PR number
3. Spawn sub-agent to execute deployment
4. Report results to user
5. **NEVER retry sub-agent work** - report failures to user

### Step 1: Validate Prerequisites

Check required tools and GitHub MCP:

1. **Validate GitHub MCP is available**:
   - Use `ToolSearch` to check if `mcp__github__pull_request_read` is available
   - If not available: ERROR "GitHub MCP not configured. Check ~/.claude/mcp.json"

2. **Validate yarn is installed**:
   ```bash
   if ! command -v yarn &> /dev/null; then
     echo "❌ yarn not found. Install: npm install -g yarn"
     exit 1
   fi
   ```

3. **Validate git repo and we're in HPP repo**:
   ```bash
   REMOTE_URL=$(git remote get-url origin 2>/dev/null)
   if [ -z "$REMOTE_URL" ]; then
     echo "❌ Not in a git repository"
     exit 1
   fi

   REPO_SLUG=$(echo "$REMOTE_URL" | sed 's/.*[:/]\([^/]*\/[^/]*\)\.git/\1/' | sed 's/.*[:/]\([^/]*\/[^/]*\)$/\1/')
   if [ "$REPO_SLUG" != "krogertechnology/hosted-payment-page" ]; then
     echo "❌ Must run from hosted-payment-page repo, found: $REPO_SLUG"
     exit 1
   fi
   ```

### Step 2: Get HPP PR Number

Extract PR number from user argument or ask:

**If user provided PR number as argument**:
- Use it directly
- Validate it's numeric

**If no argument provided**:
- Use `AskUserQuestion` to get the PR number:
  - Question: "What is the HPP PR number to deploy?"
  - Header: "HPP PR"
  - Options: This should be a text input, but since AskUserQuestion requires options, use a single option "Enter PR number" and the user can provide custom input via "Other"
  - Alternatively, just ask the user to provide the PR number as an error message

**Simpler approach**: If no argument provided, show error asking for PR number:

```
If no argument:
  echo "❌ HPP PR number required"
  echo "Usage: /auto-deploy-esperanto-review-app <HPP-PR-NUMBER>"
  exit 1
```

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

Store: PR_NUMBER

### Step 3: Determine Esperanto Repo Path

Find Esperanto repo location:

```bash
# 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
  echo "❌ Esperanto repo not found at: $ESPERANTO_PATH"
  echo "Expected repos to be siblings in: $PARENT_DIR"
  echo "Clone esperanto: gh repo clone krogertechnology/esperanto $ESPERANTO_PATH"
  exit 1
fi

echo "Found Esperanto repo: $ESPERANTO_PATH"
```

### Step 4: Spawn Deployment Sub-Agent

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

**Task Configuration**:
```
subagent_type: "general-purpose"
description: "Deploy HPP review app to Esperanto"
model: "sonnet"  # Complex workflow with multiple git operations
```

**Sub-Agent Prompt**:

```markdown
Deploy Hosted Payment Page review version to Esperanto QA stage environment.

## CONTEXT

- **HPP PR Number**: <PR_NUMBER>
- **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 GitHub MCP to load the tool first, then fetch PR details:

```
ToolSearch: "select:mcp__github__pull_request_read"
```

Then use `mcp__github__pull_request_read`:

```
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
- **Labels**: Array of label objects

Store these:
- HPP_BRANCH_NAME
- HPP_PR_TITLE

**Validate 'qa-required' label**:
- Check if labels array contains an object with name: "qa-required"
- If NOT found: ERROR "HPP PR #<PR_NUMBER> does not have 'qa-required' label. Add the label and try again."

### 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 (in reverse order, most recent first) 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.130-074e20d"
- Extract the version string (e.g., "3.0.130-074e20d")

**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 (first match when searching in reverse)

Store: REVIEW_VERSION

### Task 4: Check for Existing Esperanto PR

Use GitHub MCP to check if an Esperanto PR already exists for this branch:

```
ToolSearch: "select:mcp__github__list_pull_requests"
```

Then use `mcp__github__list_pull_requests`:

```
owner: "krogertechnology"
repo: "esperanto"
state: "open"
head: "krogertechnology:<HPP_BRANCH_NAME>"
base: "main"
```

If a PR is found:
- Store: ESPERANTO_PR_EXISTS=true
- Store: ESPERANTO_PR_NUMBER (from response)
- Store: ESPERANTO_PR_URL (html_url from response)
- Log: "Found existing Esperanto PR #<ESPERANTO_PR_NUMBER>"

If no PR found:
- Store: ESPERANTO_PR_EXISTS=false
- Log: "No existing Esperanto PR found, will create new"

### Task 5: Setup Esperanto Branch

```bash
cd <ESPERANTO_PATH>

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

# Check if branch exists remotely
if git ls-remote --heads origin "<HPP_BRANCH_NAME>" | grep -q "<HPP_BRANCH_NAME>"; then
  echo "Branch exists remotely, checking out"
  git fetch origin "<HPP_BRANCH_NAME>"
  git checkout "<HPP_BRANCH_NAME>"
  # Pull latest changes
  git pull origin "<HPP_BRANCH_NAME>"
else
  echo "Creating new branch from main"
  git checkout -b "<HPP_BRANCH_NAME>"
fi

echo "✓ On branch: <HPP_BRANCH_NAME>"
```

### Task 6: Update package.json

Use yarn to update the HPP dependency:

```bash
cd <ESPERANTO_PATH>

# Update @kroger/hosted-payment-page to review version
yarn add @kroger/hosted-payment-page@"<REVIEW_VERSION>"

YARN_EXIT=$?

if [ $YARN_EXIT -ne 0 ]; then
  echo "❌ yarn add failed with exit code: $YARN_EXIT"
  exit 1
fi

echo "✓ Updated @kroger/hosted-payment-page to <REVIEW_VERSION>"

# Verify the update
grep "@kroger/hosted-payment-page" package.json
```

**Expected Changes**:
- `package.json` should be updated with the new version
- `yarn.lock` will be updated

### 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 - version may already be deployed"
  echo "Current version in package.json:"
  grep "@kroger/hosted-payment-page" package.json

  # If Esperanto PR exists, we should still comment on HPP PR
  # If no PR exists, we can skip
  if [ "$ESPERANTO_PR_EXISTS" = "false" ]; then
    echo "Skipping - no changes needed"
    exit 0
  fi
else
  echo "✓ Verified file changes"
  git status --short
fi
```

### Task 8: Commit and Push Changes (Only if changes exist)

```bash
cd <ESPERANTO_PATH>

# Only commit if there are changes
if [ $CHANGED_FILES -gt 0 ]; then
  # Stage all changes
  git add -A

  # Create commit message
  COMMIT_MSG="chore: update @kroger/hosted-payment-page to <REVIEW_VERSION>

Automated deployment from HPP PR #<PR_NUMBER>
Review version: <REVIEW_VERSION>

Related: krogertechnology/hosted-payment-page#<PR_NUMBER>"

  git commit -m "$COMMIT_MSG"

  # Push branch
  git push -u origin "<HPP_BRANCH_NAME>"

  echo "✓ Committed and pushed changes"
fi
```

### Task 9: Create or Update Esperanto PR

**If ESPERANTO_PR_EXISTS = false** (Create new PR):

Use GitHub MCP to create PR:

```
ToolSearch: "select:mcp__github__create_pull_request"
```

Then use `mcp__github__create_pull_request`:

```
owner: "krogertechnology"
repo: "esperanto"
head: "<HPP_BRANCH_NAME>"
base: "main"
title: "[Payments] <HPP_PR_TITLE>"
body: "## WHPP Review Version Update

This PR updates the `@kroger/hosted-payment-page` dependency to review version **<REVIEW_VERSION>**.

**Related WHPP PR**: krogertechnology/hosted-payment-page#<PR_NUMBER>

---
_Auto-generated by auto-deploy-esperanto-review-app skill_"
draft: false
```

Store the response:
- ESPERANTO_PR_NUMBER (number from response)
- ESPERANTO_PR_URL (html_url from response)

**Add Labels**:

Try to add labels, but don't fail if it doesn't work:

1. Load the label tool:
   ```
   ToolSearch: "select:mcp__github__issue_write"
   ```

2. Use `mcp__github__issue_write` with method "add_labels":
   ```json
   {
     "owner": "krogertechnology",
     "repo": "esperanto",
     "issueNumber": <ESPERANTO_PR_NUMBER>,
     "method": "add_labels",
     "labels": ["Autodeploy Stage Review App", "version-minor"]
   }
   ```

3. Track the result:
   - If successful: Set LABELS_ADDED="YES"
   - If failed: Set LABELS_ADDED="NO (labels may not exist in Esperanto repo)"
   - Log the error but continue (don't exit)

**Important**: Label addition is optional - if it fails, the deployment still succeeded. User can add labels manually.

**If ESPERANTO_PR_EXISTS = true** (Update existing PR):

The push already updated the PR with new commits. Just log:
```
echo "✓ Existing Esperanto PR #<ESPERANTO_PR_NUMBER> updated with new review version"
```

### Task 10: Comment on HPP PR

Create a comment on the original HPP PR with deployment status:

Use `mcp__github__add_issue_comment`:

```
owner: "krogertechnology"
repo: "hosted-payment-page"
issueNumber: <PR_NUMBER>
body: "<EMOJI> **Esperanto Review App Deployment**

Esperanto PR has been **<ACTION>** with review version `<REVIEW_VERSION>`

**Esperanto PR**: [#<ESPERANTO_PR_NUMBER>](<ESPERANTO_PR_URL>)

_Auto-generated by auto-deploy-esperanto-review-app skill_"
```

Where:
- EMOJI: "🚀" if new PR, "🔄" if updated existing PR
- ACTION: "created" if new PR, "updated" if existing PR

### Task 11: Report Success

Display results in formatted output:

```
✓ Esperanto Review App Deployment Complete

| Field | Value |
|-------|-------|
| HPP PR | #<PR_NUMBER> |
| HPP PR Title | <HPP_PR_TITLE> |
| Review Version | <REVIEW_VERSION> |
| Branch | <HPP_BRANCH_NAME> |
| Esperanto PR | #<ESPERANTO_PR_NUMBER> |
| Esperanto PR Title | [Payments] <HPP_PR_TITLE> |
| Status | <CREATED or UPDATED> |
| Labels Added | <YES or NO (with reason if failed)> |

**Esperanto PR URL**: <ESPERANTO_PR_URL>

**Next Steps**:
- Monitor Esperanto PR CI/CD checks for autodeploy to stage
- QA testing can begin once deployed
- Comment added to HPP PR with Esperanto PR link
- If labels failed: Manually add labels "Autodeploy Stage Review App" and "version-minor" to Esperanto PR
```

## ERROR HANDLING

**Critical Errors** (stop immediately):
- HPP PR does not have 'qa-required' label
- No review version comment found
- yarn add fails
- Git operations fail
- PR creation fails
- GitHub MCP not available

**Warnings** (proceed with deployment):
- No file changes detected (version already deployed)
- Existing Esperanto PR found (update instead of create)
- Label addition fails (user can add manually)

**Non-Critical Failures** (log warning, continue):
- Label addition fails → User adds labels manually to Esperanto PR
- Comment addition fails → User can see deployment succeeded from Esperanto PR

**All errors must**:
- Log clear error message with recovery steps
- Exit immediately for critical errors (no retry)
- Provide actionable guidance to user
- For non-critical failures: Log warning and continue
```

### Step 5: Report Results

After sub-agent completes:

**On Success**:
- Display sub-agent's success message (includes deployment details table)
- Do NOT summarize or add commentary
- Success message includes next steps

**On Failure**:
- Display sub-agent's error message exactly
- Provide recovery guidance:
  - Missing 'qa-required' label → Add label to HPP PR
  - Missing version comment → Wait for review version to publish
  - yarn failure → Check Esperanto repo state and dependencies
  - GitHub MCP auth → Verify MCP server configuration
- **NEVER retry the sub-agent work yourself**

**Example Success Output**:
```
✓ Esperanto Review App Deployment Complete

| Field | Value |
|-------|-------|
| HPP PR | #328 |
| HPP PR Title | Update Kroger Rewards Card Icon |
| Review Version | 3.0.130-074e20d |
| Branch | dcpexp-133140-update-krmc-svg-icon |
| Esperanto PR | #34671 |
| Esperanto PR Title | [Payments] Update Kroger Rewards Card Icon |
| Status | CREATED |
| Labels | Autodeploy Stage Review App, version-minor |

**Esperanto PR URL**: https://github.com/krogertechnology/esperanto/pull/34671

**Next Steps**:
- Monitor Esperanto PR CI/CD checks for autodeploy to stage
- QA testing can begin once deployed
- Comment added to HPP PR with Esperanto PR link
```

---

## Verification

After skill execution, verify:

```bash
# 1. Branch exists in Esperanto (should match HPP PR branch name)
cd <path-to-esperanto-repo>
git branch --list "*<branch-name>*"

# 2. package.json updated
grep "@kroger/hosted-payment-page" package.json

# 3. PR created/updated
gh pr view <ESPERANTO-PR-NUMBER> --repo krogertechnology/esperanto --json title,labels,state

# 4. Comment added to HPP PR
gh pr view <HPP-PR-NUMBER> --repo krogertechnology/hosted-payment-page --comments | grep "Esperanto Review App Deployment"
```

---

## Security

**Safe Operations**:
- Read-only access to HPP PR (fetch details and comments)
- Creates new branch or updates existing (non-destructive)
- No force-push or destructive git operations
- Version string validated before package update

**Validation**:
- Version format: `\d+\.\d+\.\d+-[a-f0-9]+`
- PR number: numeric only
- 'qa-required' label must exist

**Authentication**:
- GitHub auth via MCP server
- No API tokens in skill code
- No PII or sensitive data

---

## Differences from upgrade-hpp Skill

| Feature | upgrade-hpp | auto-deploy-esperanto-review-app |
|---------|-------------|----------------------------------|
| PR Title Format | `<Title> \| QA Reviewer App` | `[Payments] <Title>` |
| Update Method | `update_whpp_version.sh` script | `yarn add @kroger/hosted-payment-page@VERSION` |
| Files Updated | 3 package.json files | Root package.json + yarn.lock |
| Update Existing PR | Asks user | Automatically updates |
| HPP PR Comment | No | Yes (with Esperanto PR link) |
| Label Requirement | None | Requires 'qa-required' label |

---

## Related Files

| File | Purpose |
|------|---------|
| skills/upgrade-hpp/SKILL.md | Original pattern for HPP upgrades |
| .github/workflows/auto-deploy-esperanto-review-app.yml | GitHub Actions equivalent |