/shipping-changes

name: ring:shipping-changes
description: >-
  End-to-end git orchestrator: branch → commit → push → PR, with a full plan
  presented before any execution. Detects base branch and scope allowlist once
  and propagates to all phases. Use when ready to ship a complete unit of work.
  Skip if only one phase is needed: commit-only → ring:committing-changes,
  PR-only → ring:opening-pull-requests.
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - AskUserQuestion

End-to-end shipping workflow: detect base branch and scope policy once, present a complete plan, then execute branch → commit → push → PR in sequence, confirming at each phase. Uses `ring:committing-changes` and `ring:opening-pull-requests` internally — their rules and anti-patterns apply in full.

⛔ HARD STOP — PRESENT PLAN BEFORE EXECUTING ANY MUTATING COMMAND

Read-only discovery commands (`git fetch`, `git ls-remote`, `git status`, `git diff`, `git log`) are allowed before approval — they are needed to build the plan.

MUST complete Phase 0 detection, analyze the current state, and present a complete plan to the user before running any **mutating** `git` or `gh` command (`git checkout -b`, `git add`, `git commit`, `git push`, `gh pr create`). Executing mutating commands without approval is FORBIDDEN.

---

Phase 0 — Detect Base Branch and Scope Policy

MUST complete both detections before analyzing changes or drafting anything. These values are resolved once and propagated to all subsequent phases.

0A — Detect Base Branch

# Probe A — GitHub API default (fallback: git remote show origin | grep 'HEAD branch' | awk '{print $NF}')
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

# Probe B — PR template hint: read .github/pull_request_template.md for explicit branch name

# Probe C — develop existence
git ls-remote --heads origin develop

Apply precedence in order — first match wins:

| Priority | Source | Rule | |----------|--------|------| | **1 — highest** | PR template | Explicit branch name in `.github/pull_request_template.md` — overrides everything | | **2** | develop + user | Probe C finds `develop` AND differs from Probe A → ask user to confirm which target | | **3 — fallback** | GitHub API | Use value from Probe A | | **4** | Neither | STOP — ask the user |

**Why not develop-first:** a repo may have a stale `develop` branch while the real PR target is `main`. The GitHub API is the authoritative source; `develop` existence triggers a confirmation step instead of a silent assumption.

0B — Detect Scope Policy

Check in this order:

1. `.github/workflows/pr-validation.yml` (primary) 2. `.github/workflows/pr-title.yml` 3. `.github/workflows/commitlint.yml` 4. `.github/workflows/semantic-pull-request.yml` 5. Root configs: `commitlint.config.{js,cjs,mjs,ts}`, `.commitlintrc*`

Extract the allowed `scope` list and any `type` restrictions.

| Situation | Required Action | |-----------|-----------------| | Policy found, scope is clear | Use only scopes from the allowlist | | Policy found, scope is ambiguous | STOP and ask the user which allowed scope to use | | No policy file found | MUST still include a scope — ask the user what scope to use |

---

Phase 0C — Analyze Current State

git status
git branch
git diff
git log --oneline -5

Use this output for the plan.

---

Phase 0D — Present Full Plan for Approval

Present everything before touching git:

Shipping Plan — waiting for your approval
──────────────────────────────────────────
Base branch:    develop   (from: git ls-remote)
Scope policy:   .github/workflows/pr-validation.yml → scopes: [api, auth, docs, ci]
Chosen scope:   auth

Phase 1 — Branch
  Current branch: main → will create: feat/add-oauth2-refresh
  Command: git checkout -b feat/add-oauth2-refresh origin/develop

Phase 2 — Commit
  Files to stage:
    - src/auth/oauth.ts (modified)
    - src/auth/oauth.test.ts (modified)
    - docs/auth/oauth-setup.md (modified)
  Proposed commits:
    1. feat(auth): add OAuth2 refresh token support
    2. docs(docs): update OAuth2 setup guide

Phase 3 — Push
  Command: git push -u origin feat/add-oauth2-refresh

Phase 4 — Pull Request
  Title:   feat(auth): add OAuth2 refresh token support
  Base:    develop
  Command: gh pr create --title "..." --body "..." --base develop

Approve and execute? [Yes / Modify / Cancel]

MUST wait for explicit user approval. Do NOT begin Phase 1 until approved.

---

Phase 1 — Branch

1.1 — Check current branch

If already on a feature branch (not `$BASE`, not `main` when `$BASE=develop`):

AskUserQuestion({
  questions: [{
    question: "You're already on a feature branch. How should I proceed?",
    header: "Branch",
    options: [
      { label: "Use current branch", description: "Continue on this branch" },
      { label: "Create new branch", description: "Create a new branch from origin/$BASE" }
    ]
  }]
});

1.2 — Create branch (if needed)

Branch naming convention: `<type>/<description>` in kebab-case.

git fetch origin --quiet
# Check for duplicate
git ls-remote --heads origin <type>/<description>

# If no duplicate:
git checkout -b <type>/<description> origin/$BASE

If a branch with the same name already exists on remote, ask the user for a different name.

Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `perf`

---

Phase 2 — Commit

Delegate to `ring:committing-changes` with the resolved `$BASE` and scope policy as context.

**MUST propagate `$BASE`** to `ring:committing-changes` — Step 7 of that skill uses `origin/$BASE..HEAD` for commit batch scoping. Without it, the skill falls back to `@{u}` or re-detects the base, which works but is redundant when `$BASE` is already known here.

The following rules from `ring:committing-changes` apply in full:

• `$BASE` is already resolved — pass it explicitly so Step 7 skips re-detection
• Scope MUST come from the allowlist resolved in Phase 0B
• Scope MUST be