github-stack-setup

What It Does

Verifies that this machine can act as the github provider of the
stacked-pr capability group, and reports exactly what is missing. It
checks three things:

1. gh is installed and at least v2.0.
2. gh auth status succeeds.
3. The installed gh stack extension is the official github/gh-stack
   — verified by owner in gh extension list, not by the command
   resolving. Several third-party extensions expose the same gh stack
   command name.

It installs nothing on its own and runs no stack operation. Extension
installation is offered, never performed silently.

When to Use

• First installing github-workflow.
• After changing gh authentication or reinstalling the GitHub CLI.
• When /stack:status reports PARTIAL_TOOLING for the github provider.

Usage

Step 1: Probe prerequisites

plugins/yellow-core/lib/stack-tooling-probe.js is the single owner of
this logic — do not re-derive gh presence, auth validity, or extension
identity here. Run this single Bash call and read its JSON output.

set -uo pipefail

PROBE="${CLAUDE_PLUGIN_ROOT}/../yellow-core/lib/stack-tooling-probe.js"
if [ ! -f "$PROBE" ]; then
  printf 'stack_provider_error: tooling probe not found at %s (is yellow-core installed?)\n' "$PROBE"
  exit 0
fi

node "$PROBE" probe --provider github

Step 2: Report

Read the github object's readiness (ready/not-ready/unknown) and
checks (present, version, authValid, extensionIdentity:
verified/wrong-owner/missing/unavailable). Print each check, then
classify:

• READY — readiness: "ready" (requires present, authValid, and
  extensionIdentity: "verified" together).
• NEEDS SETUP — anything else.

Name the specific gap using detail and checks.extensionIdentity.
"Install the official extension with gh extension install github/gh-stack" is useful; "prerequisites missing" is not.

If extensionIdentity is wrong-owner, say so explicitly: a third-party
gh stack will answer commands but is not the extension this provider
targets, and it must be removed before installing the official one.

If readiness is unknown, say so explicitly: the probe could not
determine readiness (a gh auth status or gh extension list failure,
not a "not installed" result) — treat it as unresolved, not as NEEDS SETUP/MISSING.

Step 3: Offer the install (never perform it silently)

Both offers below additionally require checks.present: true and
checks.authValid: true — an unauthenticated gh must never reach gh extension install/remove. If either is false, report that gap and stop;
do not offer either flow, regardless of what extensionIdentity reports.

If extensionIdentity is missing and gh is present and authenticated,
use AskUserQuestion to offer:

• "Install github/gh-stack" — on confirmation, run
  gh extension install github/gh-stack, then re-run Step 1 and report.
• "Skip" — report the gap and stop.

If extensionIdentity is wrong-owner and gh is present and
authenticated, the official extension cannot be installed until the
third-party one is gone — use AskUserQuestion to offer the
remove-then-install flow instead:

• "Remove the third-party extension and install github/gh-stack" — on
  confirmation, run gh extension remove stack (the command name is
  shared, so this removes whichever extension currently provides it),
  then gh extension install github/gh-stack, then re-run Step 1 and
  report.
• "Skip" — report the gap and stop.

If extensionIdentity is unavailable, do not offer either flow — report
that the extension state could not be determined and stop.

Both install commands are deliberately unpinned. --pin is the right
call for a third-party extension, but github/gh-stack is first-party
(the Step 1 identity check exists to guarantee that) and is still in
active preview, so pinning would freeze every installer to a tag that
goes stale as GitHub ships fixes, in exchange for no reduction in trust
surface for someone already running gh. Revisit if gh-stack leaves
preview or ownership changes.

Do not offer to install gh itself, change authentication, or install the
gh skill package: gh skill is an explicitly preview surface ("subject to
change without notice") and nothing in this plugin depends on it.

Step 4: Do not switch providers

This skill never enables or disables a plugin. If the user wants to make
github the active provider, direct them to /stack:select github — the
provider-neutral command in yellow-core. Say it plainly; do not run it.

Boundaries

• Read-only apart from the confirmed gh extension install, and — for the
  WRONG OWNER replacement flow only — the confirmed gh extension remove stack that immediately precedes it. Both mutations require explicit
  AskUserQuestion confirmation; nothing else is mutated.
• Never invokes gh stack init, add, submit, push, sync, rebase,
  modify, merge, link, or unstack.
• Never touches gt, Graphite configuration, or gt-workflow.
• Never edits settings JSON, branch protections, rulesets, merge queues, or
  required checks.