@celsoft/coordinator 0.0.0 → 0.1.0

package/skills/default/skills/git-workflow/mise-tasks/_lib.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env zsh
+# Shared helpers for the layout tasks. Not a task itself (leading underscore).
+# DEV_ROOT and the two path helpers below are the sole definition of the repo/worktree
+# layout. SKILL.md documents it; every other skill defers to it rather than hardcoding.
+
+[[ -n "${MISE_ORIGINAL_CWD}" ]] && cd "$MISE_ORIGINAL_CWD"
+
+header()  { print -P "\n%B$*%b" >&2; }
+success() { print -P "%F{green}✓%f $*" >&2; }
+info()    { print -P "%F{cyan}•%f $*" >&2; }
+warn()    { print -P "%F{yellow}!%f $*" >&2; }
+error()   { print -P "%F{red}✗%f $*" >&2; }
+dim()     { print -P "%F{8}$*%f" >&2; }
+# Every task's only stdout is its final resolved path, printed with `path`, so a
+# caller captures it with $(...) instead of re-deriving repo_path/worktree_path
+# itself. Human-readable progress above goes to stderr and is unaffected.
+path()    { print "$*"; }
+
+DEV_ROOT="${DEVELOPMENT_ROOT:-$HOME/Development}"
+
+repo_path()     { print "$DEV_ROOT/repos/$1/$2"; }
+worktree_path() { print "$DEV_ROOT/worktrees/$3/$1/$2"; }
+
+# Branches may contain slashes (e.g. env/sean/RKG-7734), which nest as real
+# directories. That makes the branch/org boundary unrecoverable from the path,
+# so anything reading a worktree back asks git rather than parsing.
+branch_of() { git -C "$1" branch --show-current; }
+
+# A caller hands over whatever checkout it happens to be sitting in, which may be
+# a linked worktree. Its refs, remotes and worktree list are the main checkout's,
+# so resolve to that one and treat the two identically.
+main_checkout() {
+    local common
+    common=$(git -C "$1" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 1
+    print "${common:h}"
+}
+
+# org/repo comes from origin's URL, never from where the checkout sits on disk:
+# that is what lets a clone outside repos/ (a tool's own source directory, say)
+# still land its worktrees under its own org/repo with the rest of the set.
+# Handles ssh aliases (git@github.com-acme:org/repo.git) and https alike.
+repo_slug() {
+    local url remote_path org repo
+    url=$(git -C "$1" config --get remote.origin.url 2>/dev/null)
+    if [[ -n "$url" ]]; then
+        remote_path=${url%.git}
+        remote_path=${remote_path#*://}
+        remote_path=${remote_path#*@}
+        remote_path=${remote_path/:/\/}
+    else
+        # No remote to ask: the checkout and its parent stand in for repo and org.
+        remote_path=${1:A}
+    fi
+    repo=${remote_path:t}
+    org=${${remote_path:h}:t}
+    if [[ -z "$org" || -z "$repo" ]]; then
+        error "Cannot determine org/repo for $1"
+        dim "  Set a remote: git -C $1 remote add origin git@github.com:<org>/<repo>.git"
+        return 1
+    fi
+    print "$org/$repo"
+}
+
+need_git() {
+    if ! command -v git &>/dev/null; then
+        error "'git' is not on PATH."
+        exit 1
+    fi
+}
+
+require_checkout() {
+    if ! git -C "$1" rev-parse --git-dir &>/dev/null; then
+        error "Not a git checkout: $1"
+        exit 1
+    fi
+}
+
+# origin/HEAD is only populated by a full clone or an explicit set-head, so ask the
+# remote before giving up. Never guess a name: branching a new worktree off the wrong
+# base looks like it worked, so an undeterminable default is a hard error the caller
+# resolves with the user.
+# An explicit base. Prefer the remote ref: a stale local branch of the same name is the
+# likelier mistake. Never invent one: an unresolvable base is a hard error, because
+# branching off the wrong commit reports success just as loudly as branching off the right
+# one.
+resolve_base() {
+    local dir="$1" base="$2"
+    git -C "$dir" show-ref --verify --quiet "refs/remotes/origin/$base" \
+        && { print "origin/$base"; return }
+    git -C "$dir" show-ref --verify --quiet "refs/heads/$base" \
+        && { print "$base"; return }
+    error "Base branch '$base' does not exist locally or on origin in $dir"
+    dim "  Check the name, or fetch first: git -C $dir fetch origin"
+    return 1
+}
+
+default_branch() {
+    local dir="$1" ref
+    ref=$(git -C "$dir" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null) \
+        && { print "${ref#refs/remotes/origin/}"; return }
+    git -C "$dir" remote set-head origin --auto >/dev/null 2>&1 \
+        && ref=$(git -C "$dir" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null) \
+        && { print "${ref#refs/remotes/origin/}"; return }
+    error "Cannot determine the default branch of origin in $dir"
+    dim "  Set it explicitly: git -C $dir remote set-head origin <branch>"
+    return 1
+}

package/skills/default/skills/git-workflow/mise-tasks/clone

@@ -0,0 +1,36 @@
+#!/usr/bin/env zsh
+#MISE description="Clone <org>/<repo> into $DEVELOPMENT_ROOT/repos/<org>/<repo> (idempotent)"
+#USAGE arg "<org>" help="GitHub org or user"
+#USAGE arg "<repo>" help="Repository name"
+
+source "${0:A:h}/_lib.sh"
+
+org="${1:?usage: clone <org> <repo>}"
+repo="${2:?usage: clone <org> <repo>}"
+
+need_git
+
+dest=$(repo_path "$org" "$repo")
+
+if [[ -d "$dest/.git" ]]; then
+    success "Already cloned: $dest"
+    path "$dest"
+    exit 0
+fi
+
+if [[ -e "$dest" ]]; then
+    error "$dest exists but is not a git clone."
+    exit 1
+fi
+
+# SSH so any per-org keys and URL rewrites apply.
+info "Cloning $org/$repo into $dest..."
+mkdir -p "${dest:h}"
+if ! git clone "git@github.com:$org/$repo.git" "$dest"; then
+    error "Clone failed for $org/$repo."
+    dim "  If this is an auth or permission error, the SSH key in use is not one GitHub accepts for '$org'."
+    exit 1
+fi
+
+success "Cloned to $dest"
+path "$dest"

package/skills/default/skills/git-workflow/mise-tasks/repo-list

@@ -0,0 +1,8 @@
+#!/usr/bin/env zsh
+#MISE description="List every clone under $DEVELOPMENT_ROOT/repos as org/repo"
+
+source "${0:A:h}/_lib.sh"
+
+for dir in "$DEV_ROOT"/repos/*/*(N/); do
+    [[ -d "$dir/.git" ]] && print "${${dir%/}#$DEV_ROOT/repos/}"
+done

package/skills/default/skills/git-workflow/mise-tasks/unpushed

@@ -0,0 +1,26 @@
+#!/usr/bin/env zsh
+#MISE description="Print every commit a push would send, oldest first, with full messages"
+
+source "${0:A:h}/_lib.sh"
+
+need_git
+
+default=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null)
+git fetch --quiet origin 2>/dev/null || warn "Fetch failed; comparing against the last known remote state."
+
+# A linked worktree pushes by fast-forwarding the default branch, so that is the target.
+# A clone pushes its own branch: its upstream if set, else the default branch.
+if [[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]]; then
+    base=$default
+else
+    base=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null) || base=$default
+fi
+
+if [[ -z "$base" ]]; then
+    error "No upstream and no origin/HEAD to compare against."
+    exit 1
+fi
+
+count=$(git rev-list --count "$base..HEAD")
+info "$count unpushed commit(s) on $(git branch --show-current), compared with $base"
+git log --reverse --format='%h %s%n%n%b' "$base..HEAD"

package/skills/default/skills/git-workflow/mise-tasks/worktree-add

@@ -0,0 +1,60 @@
+#!/usr/bin/env zsh
+#MISE description="Add a worktree at $DEVELOPMENT_ROOT/worktrees/<branch>/<org>/<repo> (idempotent)"
+#USAGE arg "<src>" help="Path to any checkout of the repo; a linked worktree is fine"
+#USAGE arg "<branch>" help="Branch name; slashes nest as directories"
+#USAGE arg "[base]" help="Branch to create from; defaults to the repo's default branch"
+
+source "${0:A:h}/_lib.sh"
+
+src="${usage_src:?usage: worktree-add <src> <branch> [base]}"
+branch="${usage_branch:?usage: worktree-add <src> <branch> [base]}"
+base="${usage_base:-}"
+
+need_git
+require_checkout "$src"
+
+# The source is the only thing a caller has to know. Where the worktree goes
+# follows from origin's org/repo, so a checkout anywhere on disk still lands its
+# worktrees with the rest of that branch's set.
+src=$(main_checkout "$src")
+slug=$(repo_slug "$src") || exit 1
+dest=$(worktree_path "${slug%/*}" "${slug#*/}" "$branch")
+
+# git worktree add prints "HEAD is now at ..." on stdout, which would otherwise
+# ride along with the path a caller captures. Every one of the three is >&2.
+if [[ -d "$dest" ]]; then
+    success "Worktree already exists: $dest"
+    dim "  On branch: $(branch_of "$dest")"
+    path "$dest"
+    exit 0
+fi
+
+git -C "$src" fetch origin --prune --quiet 2>/dev/null
+
+mkdir -p "${dest:h}"
+
+# The branch existing already settles where it came from, so a base is moot. Say so
+# rather than ignoring it: a caller that passed one believes it is taking effect.
+if git -C "$src" show-ref --verify --quiet "refs/heads/$branch"; then
+    [[ -n "$base" ]] && warn "Ignoring base '$base': local branch '$branch' already exists."
+    info "Checking out existing local branch '$branch'..."
+    git -C "$src" worktree add "$dest" "$branch" >&2
+elif git -C "$src" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
+    [[ -n "$base" ]] && warn "Ignoring base '$base': remote branch 'origin/$branch' already exists."
+    info "Tracking existing remote branch 'origin/$branch'..."
+    git -C "$src" worktree add --track -b "$branch" "$dest" "origin/$branch" >&2
+else
+    if [[ -n "$base" ]]; then
+        start=$(resolve_base "$src" "$base") || exit 1
+    else
+        default=$(default_branch "$src") || exit 1
+        start="origin/$default"
+    fi
+    # --no-track: branching off a remote-tracking ref otherwise sets that ref as upstream
+    # (branch.autoSetupMerge), so a later bare `git push` would target the base branch.
+    info "Creating new branch '$branch' from $start..."
+    git -C "$src" worktree add --no-track -b "$branch" "$dest" "$start" >&2
+fi
+
+success "Worktree ready: $dest"
+path "$dest"

package/skills/default/skills/github/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: github
+verified: 2026-09-03
+description: "MUST READ before running any `gh` command that touches a repo, PR, or issue: several GitHub accounts are logged in at once, and this routes each command to the account that has access to the target org. Also covers stacked pull requests, verifying GitHub features against the live API rather than memory, installing `gh` via Homebrew when it is missing, and adding an account when auth fails."
+---
+
+# GitHub CLI (`gh`), org-aware
+
+The machine has **more than one GitHub account logged into `gh`** (a personal one, one per company org). Only one is "active", and it is whichever was switched to last: so a bare `gh pr create` regularly runs as the wrong identity and fails with a confusing *"Could not resolve to a Repository"*.
+
+The fix is per-command, not global: this skill's `scripts/gh-org` picks the account for the **target org** and injects that account's token as `GH_TOKEN` for one invocation. Nothing global is switched, so parallel sessions on different orgs don't fight.
+
+This wires the **API** side (`gh`). The **SSH/git** side (push, clone) is separate: an SSH key GitHub accepts for the org. Having one set up says nothing about the other. `git-workflow` owns commit rules, per-repo identity, and the on-disk repo/worktree layout.
+
+## The rule
+
+Anything that touches a repo, PR, issue, run, or org goes through:
+
+```bash
+<skill>/scripts/gh-org run [<org>] -- gh <args>...
+```
+
+Omit `<org>` inside a git repo: it is parsed from the `origin` remote. Pass it explicitly when outside a repo or when targeting another org.
+
+Bare `gh` is fine only for account-agnostic commands: `gh --version`, `gh auth status`, `gh auth login`.
+
+**Never `gh repo clone`.** It writes into the current directory and ignores the on-disk layout. Cloning belongs to the `git-workflow` skill: read its **Repo layout** section and run its `clone` task, which places the repo correctly and uses SSH so the org keys apply.
+
+Examples:
+
+```bash
+scripts/gh-org run -- gh pr create --fill                       # org from the remote
+scripts/gh-org run -- gh pr list --state open
+scripts/gh-org run -- gh pr checks
+scripts/gh-org run acme -- gh issue view 42 --repo acme/api --json title,body
+scripts/gh-org run octo-user -- gh repo list --limit 20
+```
+
+The script prints `gh-org: running as '<account>' for org '<org>'` to stderr: quote that account when reporting to the user, so they know which identity acted.
+
+## GitHub ships faster than your knowledge
+
+Your training cutoff is older than GitHub's release cadence, so a feature you don't remember is more likely new than nonexistent. Assume that by default.
+
+**When the user names a GitHub capability, verify before building anything.** Stacked PRs, merge queues, rulesets, sub-issues, Projects, auto-merge: check whether it exists as a first-party feature *before* hand-rolling an equivalent:
+
+```bash
+gh <thing> --help                 # is there a built-in command?
+gh extension list                 # is it an extension you don't have?
+scripts/gh-org run -- gh api repos/<org>/<repo>/pulls/<n> | jq 'keys'   # does the object carry its fields?
+```
+
+Then check https://github.blog/changelog for anything newer than you remember. If the feature exists and you were about to build a manual substitute, say so and let the user choose: don't quietly ship the substitute.
+
+**A user correcting you on a matter of fact is a signal to go verify, not to argue.** If they say "that's a feature now" and you believe otherwise, check before replying. Producing more evidence for your existing answer is the failure mode.
+
+## Never claim a first-party feature is in use without reading it back
+
+Doing something that *resembles* a feature is not using it. Chaining base branches by hand is not a stack; a label named "merge queue" is not a merge queue.
+
+Before telling the user a GitHub feature is active, query the object and show the field that proves it. If the field is absent, say the feature is not in use and name what you actually did instead. This applies to your own prior work in the session: re-check rather than trusting what you said earlier.
+
+## Stacked pull requests
+
+First-party since 2026-07-30 (public preview). A stack is real GitHub state, not a base-branch convention.
+
+**Identifying one:** a stacked PR carries a `stack` object in the REST payload (stack number and size, plus the PR's position and base); GraphQL exposes read-only `stack` and `stackEntry` fields on `PullRequest`. No `stack` key means it is not a stack, whatever the base branch says:
+
+```bash
+scripts/gh-org run -- gh api repos/<org>/<repo>/pulls/<n> --jq 'has("stack")'
+```
+
+**Requirements:** `gh` 2.90.0+, git 2.20+, and the extension:
+
+```bash
+gh extension install github/gh-stack
+```
+
+**Working with a stack:**
+
+| Command | What it does |
+|---|---|
+| `gh stack init` | Creates the tracking entry and the first branch |
+| `gh stack add <branch>` | Adds a branch to the stack |
+| `gh stack add -Am "<message>"` | Stages, commits, and creates the next branch in one step |
+| `gh stack push` | Pushes every branch in the stack |
+| `gh stack submit` | Opens the PRs and links them as a stack on GitHub |
+| `gh stack view` | Branches, PR links, statuses, and each branch's latest commit |
+
+**Merging** is atomic across the stack (the whole group merges, or enters the merge queue, or none of it does) and requires the asynchronous merge endpoint rather than the legacy synchronous one.
+
+**Rebasing** is handled for you: trigger a server-side cascading rebase from the PR, or run it locally through the extension. Don't hand-rebase each branch.
+
+**Converting PRs that already exist needs no rebuild.** `gh stack link` takes PR numbers, PR URLs, or branch names in stack order (bottom to top) and links them into a real stack, keeping their numbers, review history, and draft state. Branches without a PR get one created with the right base chaining; PRs already in a stack are left alone.
+
+```bash
+GH_REPO=<org>/<repo> scripts/gh-org run <org> -- gh stack link <bottom-pr> <top-pr>
+```
+
+Two gotchas, both learned the hard way:
+
+- **A custom SSH host alias breaks repo detection.** With a remote like `git@jll.github.com:org/repo.git`, `gh stack` fails with *"none of the git remotes ... point to a known GitHub host"*. There is no `--repo` flag; set `GH_REPO` instead, as above.
+- **`--open` marks every PR in the stack ready for review**, drafts included. Omit it unless that is what you want.
+
+`gh stack init <branch>...` likewise adopts existing branches rather than demanding new ones. So reach for `link` or `init` before ever proposing to rebuild a PR: the CLI's own `--help` is the authority here, and it documents more than the docs pages do.
+
+## How the account is resolved
+
+1. **The repo's own login:** inside a repo whose config sets `github.user` (a coordinator writes it, with the repo's identity and SSH key, into every repo it keeps), that login acts for the repo's own org, ahead of everything below.
+2. **Cached mapping:** `git config --global gh-org.account.<org>` (field first, org lowercased; git keys are case-insensitive, so `Acme` and `acme` are one entry).
+3. **Probe:** otherwise each logged-in account is tested: does its login equal `<org>` (personal namespace), or is it an active member of `<org>`? First match wins and is **cached** into the git config above.
+4. **Fail:** if no account has access, the script stops and says to run `gh auth login`.
+
+Manage mappings directly when the probe guesses wrong:
+
+```bash
+scripts/gh-org list                       # show org -> account mappings
+scripts/gh-org map <org> <account>        # pin one
+scripts/gh-org unmap <org>                # forget it (re-probes next time)
+scripts/gh-org account [<org>]            # print the account that would be used
+```
+
+The `gh-org.*` namespace holds the per-account git identity too: see [Git identity setup](#git-identity-setup-one-time).
+
+## A pending invite looks like access
+
+When an account should have org access but repo operations fail, check the **membership
+state** rather than inferring it from a successful login. An unaccepted org invitation
+authenticates fine and then denies every repo, which reads as a mysterious permissions bug:
+
+```bash
+scripts/gh-org run <org> -- gh api user/memberships/orgs/<org> --jq .state
+```
+
+- **`active`** access is real; the failure is something else.
+- **`pending`** the invitation was never accepted. Accept it, then re-check.
+- **the call fails** no logged-in account is a member. Add one (see below).
+
+Once it reads `active`, pin the mapping so later work cannot pick a different account:
+
+```bash
+scripts/gh-org map <org> <account>
+```
+
+Note that **API access and SSH access are independent**. A healthy `gh` login says nothing
+about whether pushes work; that needs an SSH key GitHub accepts for each org you push to.
+
+## Git identity setup (one time)
+
+Per machine, once. Commits are attributed per repo, from the account that owns the org: never from a global identity, so a work repo can't be committed to with a personal address.
+
+1. **Drop the global identity.** Git then refuses to invent one from `$USER@$HOSTNAME`:
+   ```bash
+   git config --global --unset user.name
+   git config --global --unset user.email
+   git config --global user.useConfigOnly true
+   ```
+   Existing repos relying on the global value now have no identity, and their next commit fails until one is set. That failure is the point.
+
+2. **Cache the identity for each logged-in account** (`scripts/gh-org accounts` lists them):
+   ```bash
+   scripts/gh-org set-identity <account> "Full Name" you@example.com
+   ```
+   Stored as `gh-org.name.<account>` / `gh-org.email.<account>` in the global config. Git never reads these: they are a lookup table, not an identity.
+
+3. **Verify:** `scripts/gh-org doctor` prints `GLOBAL IDENTITY:`, `USECONFIGONLY:`, and one `IDENTITY:` line per account.
+
+Then, in each repo: right after cloning, and any time a commit fails with *"Author identity unknown"*:
+
+```bash
+scripts/gh-org apply          # origin -> org -> account -> repo's --local user.name/user.email
+```
+
+`scripts/gh-org identity [<org>]` prints what `apply` would write without touching the repo. The commit-time rules live in the `git-workflow` skill.
+
+## When something fails
+
+Run `scripts/gh-org doctor`: it reports `GH:`, `BREW:`, `ACCOUNTS:`, the org mappings, and the git-identity state. Act on it:
+
+- **`GH: MISSING`:** install it and retry:
+  ```bash
+  brew install gh
+  ```
+- **`BREW: MISSING`:** Homebrew isn't set up. Install it from https://brew.sh at its standard prefix, then `brew install gh`.
+- **`ACCOUNTS: NONE`**, or the target org has no account: add one (see below).
+- **Everything `OK`:** auth is not the problem; read the actual error.
+
+## Adding an account
+
+**Claude drives this; the user only approves in the browser.** Run the login in the **background** with stdin from `/dev/null` so `gh` uses the device-code flow instead of waiting on a TTY:
+
+```bash
+gh auth login --hostname github.com --git-protocol ssh --scopes read:org,admin:public_key </dev/null
+```
+
+Then grep the output for just the code and URL and relay them verbatim:
+
+```bash
+grep -E 'one-time code|Open this URL' <output-file>
+```
+
+`read:org` is required: the org-membership probe above depends on it. Monitor until `gh` exits, then re-run `scripts/gh-org doctor`.
+
+Logging in a second account does **not** disturb the first; `gh` holds them all and `gh-org` selects between them per command.
+
+## Never print tokens
+
+Do not run `gh auth token`, `gh auth status --show-token`, or `--with-token` with a pasted PAT: those put a live credential in the transcript. `gh-org` reads the token internally and exports it only into the child process; it never prints it. See `secrets`.

package/skills/default/skills/github/scripts/gh-org

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+HOST="github.com"
+
+die() { printf 'gh-org: %s\n' "$*" >&2; exit 1; }
+note() { printf 'gh-org: %s\n' "$*" >&2; }
+lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+
+need_gh() { command -v gh >/dev/null 2>&1 || die "gh is not installed: run: brew install gh"; }
+
+accounts() {
+  gh auth status --hostname "$HOST" 2>&1 \
+    | grep -oE 'account [A-Za-z0-9._-]+' \
+    | awk '{print $2}'
+}
+
+token_for() { gh auth token --hostname "$HOST" --user "$1" 2>/dev/null; }
+
+detect_org() {
+  local url owner
+  url=$(git remote get-url origin 2>/dev/null) || return 1
+  owner=$(printf '%s' "$url" | sed -E 's#^[a-z]+://[^/]+/##; s#^[^@]+@[^:]+:##; s#/.*$##')
+  [ -n "$owner" ] || return 1
+  printf '%s\n' "$owner"
+}
+
+resolve() {
+  local org="$1" cached u tok login state match="" here
+  here=$(git config --local --get github.user 2>/dev/null || true)
+  if [ -n "$here" ] && [ "$(lower "$(detect_org 2>/dev/null || true)")" = "$(lower "$org")" ]; then
+    printf '%s\n' "$here"; return 0
+  fi
+  cached=$(git config --global --get "gh-org.account.$(lower "$org")" 2>/dev/null || true)
+  if [ -n "$cached" ]; then printf '%s\n' "$cached"; return 0; fi
+
+  while read -r u; do
+    [ -n "$u" ] || continue
+    tok=$(token_for "$u") || continue
+    [ -n "$tok" ] || continue
+    login=$(GH_TOKEN="$tok" gh api user --jq .login 2>/dev/null || true)
+    if [ "$(lower "$login")" = "$(lower "$org")" ]; then match="$u"; break; fi
+    state=$(GH_TOKEN="$tok" gh api "user/memberships/orgs/${org}" --jq .state 2>/dev/null || true)
+    if [ "$state" = "active" ]; then match="$u"; break; fi
+  done < <(accounts)
+
+  [ -n "$match" ] || die "no logged-in gh account has access to '${org}': run: gh auth login"
+  git config --global "gh-org.account.$(lower "$org")" "$match"
+  note "mapped org '${org}' -> account '${match}'"
+  printf '%s\n' "$match"
+}
+
+cmd_identity() {
+  need_gh
+  local org="${1:-}" account name email
+  [ -n "$org" ] || org=$(detect_org) || die "could not detect org from the git remote: pass it explicitly"
+  account=$(resolve "$org")
+  name=$(git config --global --get "gh-org.name.$(lower "$account")" 2>/dev/null || true)
+  email=$(git config --global --get "gh-org.email.$(lower "$account")" 2>/dev/null || true)
+  printf 'ACCOUNT: %s\n' "$account"
+  if [ -z "$name" ] || [ -z "$email" ]; then
+    printf 'IDENTITY: NONE\n'
+    die "no identity cached for account '${account}': run: gh-org set-identity ${account} \"Full Name\" you@example.com"
+  fi
+  printf 'NAME: %s\nEMAIL: %s\n' "$name" "$email"
+}
+
+cmd_set_identity() {
+  local account="${1:-}" name="${2:-}" email="${3:-}"
+  [ -n "$account" ] && [ -n "$name" ] && [ -n "$email" ] \
+    || die 'usage: gh-org set-identity <account> "Full Name" <email>'
+  git config --global "gh-org.name.$(lower "$account")" "$name"
+  git config --global "gh-org.email.$(lower "$account")" "$email"
+  printf 'IDENTITY: %s -> %s <%s>\n' "$account" "$name" "$email"
+}
+
+cmd_apply() {
+  git rev-parse --git-dir >/dev/null 2>&1 || die "not inside a git repository"
+  local out name email
+  out=$(cmd_identity "$@")
+  name=$(printf '%s\n' "$out" | sed -n 's/^NAME: //p')
+  email=$(printf '%s\n' "$out" | sed -n 's/^EMAIL: //p')
+  git config --local user.name "$name"
+  git config --local user.email "$email"
+  printf 'LOCAL IDENTITY: %s <%s>\n' "$name" "$email"
+}
+
+cmd_doctor() {
+  if command -v gh >/dev/null 2>&1; then
+    printf 'GH: OK %s (%s)\n' "$(command -v gh)" "$(gh --version | head -1 | awk '{print $3}')"
+  else
+    printf 'GH: MISSING\n'
+  fi
+  if command -v brew >/dev/null 2>&1; then
+    printf 'BREW: OK %s\n' "$(command -v brew)"
+  else
+    printf 'BREW: MISSING\n'
+  fi
+  if command -v gh >/dev/null 2>&1; then
+    local list
+    list=$(accounts | tr '\n' ' ')
+    [ -n "${list// /}" ] && printf 'ACCOUNTS: %s\n' "$list" || printf 'ACCOUNTS: NONE\n'
+  fi
+  cmd_list
+  cmd_identities
+}
+
+cmd_identities() {
+  local gname gmail line
+  gname=$(git config --global --get user.name 2>/dev/null || true)
+  gmail=$(git config --global --get user.email 2>/dev/null || true)
+  if [ -n "$gname" ] || [ -n "$gmail" ]; then
+    printf 'GLOBAL IDENTITY: SET %s <%s>: remove it (see the git-workflow skill)\n' "$gname" "$gmail"
+  else
+    printf 'GLOBAL IDENTITY: NONE\n'
+  fi
+  if [ "$(git config --global --get user.useConfigOnly 2>/dev/null || true)" = "true" ]; then
+    printf 'USECONFIGONLY: OK\n'
+  else
+    printf 'USECONFIGONLY: OFF: run: git config --global user.useConfigOnly true\n'
+  fi
+  if ! git config --global --get-regexp '^gh-org\.email\.' >/dev/null 2>&1; then
+    printf 'IDENTITIES: NONE\n'; return 0
+  fi
+  git config --global --get-regexp '^gh-org\.email\.' | while read -r line; do
+    local acct; acct=$(printf '%s' "${line%% *}" | sed -E 's#^gh-org\.email\.##')
+    printf 'IDENTITY: %s -> %s <%s>\n' \
+      "$acct" "$(git config --global --get "gh-org.name.${acct}" 2>/dev/null || printf '?')" "${line#* }"
+  done
+}
+
+cmd_list() {
+  local line
+  if ! git config --global --get-regexp '^gh-org\.account\.' >/dev/null 2>&1; then
+    printf 'MAPPINGS: NONE\n'; return 0
+  fi
+  git config --global --get-regexp '^gh-org\.account\.' | while read -r line; do
+    printf 'MAPPING: %s -> %s\n' \
+      "$(printf '%s' "${line%% *}" | sed -E 's#^gh-org\.account\.##')" \
+      "${line#* }"
+  done
+}
+
+cmd_account() {
+  need_gh
+  local org="${1:-}"
+  [ -n "$org" ] || org=$(detect_org) || die "could not detect org from the git remote: pass it explicitly"
+  resolve "$org"
+}
+
+cmd_map() {
+  local org="${1:-}" login="${2:-}"
+  [ -n "$org" ] && [ -n "$login" ] || die "usage: gh-org map <org> <gh-account>"
+  git config --global "gh-org.account.$(lower "$org")" "$login"
+  printf 'MAPPING: %s -> %s\n' "$org" "$login"
+}
+
+cmd_unmap() {
+  local org="${1:-}"
+  [ -n "$org" ] || die "usage: gh-org unmap <org>"
+  git config --global --unset-all "gh-org.account.$(lower "$org")" 2>/dev/null || true
+  printf 'UNMAPPED: %s\n' "$org"
+}
+
+cmd_run() {
+  need_gh
+  local org=""
+  if [ "${1:-}" != "--" ]; then org="${1:-}"; shift || true; fi
+  [ "${1:-}" = "--" ] || die "usage: gh-org run [<org>] -- <command>..."
+  shift
+  [ $# -gt 0 ] || die "no command given"
+  [ -n "$org" ] || org=$(detect_org) || die "could not detect org from the git remote: pass it explicitly"
+
+  local user tok
+  user=$(resolve "$org")
+  tok=$(token_for "$user")
+  [ -n "$tok" ] || die "no token for account '${user}': run: gh auth login"
+  note "running as '${user}' for org '${org}'"
+  export GH_TOKEN="$tok"
+  unset GITHUB_TOKEN
+  exec "$@"
+}
+
+case "${1:-}" in
+  doctor)  shift; cmd_doctor "$@" ;;
+  accounts) shift; need_gh; accounts ;;
+  account) shift; cmd_account "$@" ;;
+  list)    shift; cmd_list ;;
+  identity) shift; cmd_identity "$@" ;;
+  set-identity) shift; cmd_set_identity "$@" ;;
+  apply)   shift; cmd_apply "$@" ;;
+  map)     shift; cmd_map "$@" ;;
+  unmap)   shift; cmd_unmap "$@" ;;
+  run)     shift; cmd_run "$@" ;;
+  *) die "usage: gh-org {doctor|accounts|account [<org>]|list|map <org> <account>|unmap <org>|identity [<org>]|set-identity <account> <name> <email>|apply [<org>]|run [<org>] -- <command>...}" ;;
+esac