Ring:Shipping Changes

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

bashCopy code
# 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:

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.

Phase 0C — Analyze Current State

bashCopy code
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:

Copy code
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):

javascriptCopy code
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.

bashCopy code
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 included in every commit message — never omit
• Commits MUST be atomic and logically grouped
• Trailers via --trailer "X-Lerian-Ref: 0x1", NEVER inside -m
• GPG sign with -S (no fallback — if no key, stop and instruct user to configure one)

Phase 3 — Push

bashCopy code
git push -u origin <current-branch>

Show the user:

• Branch name
• Number of commits being pushed
• Short summary of those commits

Confirm success before proceeding to Phase 4.

NEVER use --force or --force-with-lease unless the user explicitly requests it.

Phase 4 — Pull Request

Delegate to ring:opening-pull-requests with the resolved $BASE and scope policy as context.

The following rules from ring:opening-pull-requests apply in full:

• PR title MUST carry type(scope): description with scope from allowlist
• Body MUST fill the repo's PR template
• MUST verify base branch after gh pr create
• MUST retarget with gh pr edit <number> --base $BASE if base is wrong
• MUST return PR URL after confirmed success

Arguments

If an argument is provided (e.g., /ring:shipping-changes feat/add-oauth2), parse it as <type>/<description> for the branch name and skip the branch-naming question.

Anti-Patterns (FORBIDDEN)

• Do NOT execute any git or gh command before presenting the plan and getting approval
• Do NOT hardcode --base develop or --base main — always use $BASE resolved in Phase 0A
• Do NOT skip Phase 0B scope detection — missing scope breaks PR validation
• Do NOT omit scope in commit messages or PR title
• Do NOT invent scopes not in the allowlist — ask the user if unclear
• Do NOT use --force on push unless the user explicitly asks
• Do NOT skip the post-PR-create base verification (delegated to ring:opening-pull-requests)
• Do NOT proceed to the next phase if the current phase fails — stop and ask the user

Anti-Rationalization Table