git:20261004.b38d61b to git:20261014.0f16275

- When a Claude Code on-the-web session starts, the harness usually creates a fresh branch (e.g. `claude/add-foo-bar-XXXX`) and checks it out. This skill **discards that auto-branch** and re-points the working tree at an existing branch or PR head so the rest of the session continues that work.

- The obvious trigger is an explicit `/from-branch …` invocation. But a session can also **start** with a launch prompt that just names an existing branch to continue — with no literal `/from-branch`. Common shapes:

- - "continue the work on `<branch>`", "pick up `<branch>`", "keep going on `#123`".

- These are the **same signal**: the harness has put you on a fresh auto-branch, but the operator's intent is to attach to the _named_ existing branch and continue its work — not to start new work on the auto-branch. Treat such a launch prompt as an implicit `/from-branch <that-branch> <the rest of the prompt as follow-up>` and run this skill: resolve the named branch as the **Target** (Step 1), and take everything else in the prompt as the **Follow-up** (a bare `go`/`implement`/`execute` → run the plan under `docs/plans/`; anything richer → free-form follow-up). The tell is a launch prompt whose subject is an _existing_ branch/PR the session is not already on — when in doubt, `git ls-remote --heads origin <name>` confirms the branch exists before attaching.

- 1. **Target** (required, first token): a branch name, a `#NNN` PR number, or **any URL that carries a PR number** — a bare PR URL (`https://github.com/<owner>/<repo>/pull/NNN`) or a deep link into that PR: a review link (`.../pull/NNN#pullrequestreview-<id>`), a review-comment link (`.../pull/NNN#discussion_r<id>`), a conversation-comment link (`.../pull/NNN#issuecomment-<id>`), or a tab/file URL (`.../pull/NNN/files`, `.../pull/NNN/commits/<sha>`, …). The PR number `NNN` after `/pull/` is the basis; the `#fragment`, trailing path, and any `?query` are stripped when resolving the branch (see Step 1), but a review/comment fragment is worth keeping as a pointer to _which_ feedback the operator wants addressed.

- - another skill — a first token that names a directory under `.claude/skills/`, the rest being its arguments (e.g. `finalize and merge`, `check-merge`), with or without its slash (`@.claude/skills/CLAUDE.md` says why it comes bare) — if so, load and follow that skill **after** the attach step completes, or

- - the keyword **`go`** (or its synonyms **`implement`** / **`execute`**), optionally trailed by "the plan" / "plan" filler, meaning "execute the plan file a prior `/plan` session left under `docs/plans/`". Bare, with no plan named, it still means "implement the plan". Step 6 dispatches it.

- - `/from-branch #123 finish the migration and push` — attach, then do the described work.

- - `/from-branch #123 implement the plan` — same thing (`implement` is a synonym and the trailing "the plan" is just filler).

- - `/from-branch #123 finalize` — attach, then invoke `@.claude/skills/finalize/SKILL.md`.

- - `/from-branch https://github.com/<owner>/<repo>/pull/123#pullrequestreview-999` — a review deep link: parse `123` as the PR, attach to its branch, and treat that review's comments as the feedback to address.

- This remote execution environment has **both** the `gh` CLI **and** a populated `GH_TOKEN` environment variable available. Prefer `gh` for branch/PR operations in this skill — the GitHub MCP tools (`mcp__github__*`) are scoped to a narrow allowlist and will refuse some branch-level actions you need here (e.g. checking out a PR head, fetching arbitrary refs, pushing). If a step seems blocked by MCP restrictions, fall back to `gh` / plain `git` over HTTPS using `GH_TOKEN`. Do **not** assume the MCP restriction means the action is impossible — `gh` will work.

- - **`#NNN`, a PR URL, or any deep link into a PR** → the branch is keyed off the **PR number**, so first extract it. Don't hand a fragment-bearing URL straight to `gh` — a trailing `#pullrequestreview-…` / `#discussion_r…` / `#issuecomment-…`, a `/files`|`/commits/<sha>` path, or a `?query` can confuse it. Pull `NNN` out of the URL with a `pull/(\d+)` match and resolve the bare number: `gh pr view <NNN> --json number,headRefName,headRepository,headRepositoryOwner,isCrossRepository,state,url` (a bare `#NNN` needs no extraction). The branch you want is `headRefName`. If `isCrossRepository` is true, the PR is from a fork — note this; the remote will be the fork, not `origin`.

- - **If the link carried a review/comment fragment**, it's telling you _which_ feedback to act on — resolve it so the follow-up is grounded in it. `#pullrequestreview-<id>` is a review (its inline comments carry the substance even when the review body is just "see below" — read them with `gh api repos/<owner>/<repo>/pulls/<NNN>/reviews/<id>/comments`, or the equivalent MCP `get_review_comments`; for the whole PR — every review and thread, each quoting the lines its comment hangs off — `python3 scripts/export-github-item.py <NNN>` writes it to `docs/pr/<NNN>/pr.md`, indexed so you can open the threads you need rather than the document); `#discussion_r<id>` is one review comment; `#issuecomment-<id>` is a conversation comment. Treat addressing that feedback as the implicit follow-up when the operator didn't spell one out.

- - **Plain branch name** → use it as-is. Confirm it exists on `origin` with `git ls-remote --heads origin <branch>` (or on the fork remote if the user gave `owner:branch`).

- If resolution fails (PR not found, branch doesn't exist on the remote), **stop and report** — do not silently fall back to the auto-branch. **Lead the report with one cause, because it is the common one by far: the session is pointed at the wrong repository.** The repo is chosen per session from a dropdown above the input box, and with many in the list it is easy to leave the previous one selected — so a session meant for `owner/A` runs against `owner/B`, where the named branch genuinely isn't there. A missing branch is thus weak evidence the *branch* is wrong and strong evidence the *repo* is. So ask that first and plainly: name the repo this session is attached to (`git remote -v`) and ask whether it's the one they meant. The typo / never-pushed / already-merged theories come second, and only once the operator confirms the repo is right.

- **Always look for any PRs on the target branch — open _or_ closed — and skim them before doing anything else.** Even when the target is a plain branch name (not a `#NNN`/URL), the branch usually has PR history that tells you what the work is, what's already been reviewed, and whether an earlier PR was closed/merged/superseded. Run `gh pr list -R <owner>/<repo> --head <branch> --state all --json number,title,state,url,isDraft,baseRefName`, then for each hit skim its body, commits, and reviews (`gh pr view <NNN> -R <owner>/<repo> --json body,commits,reviews,comments,mergeable,mergeStateStatus,isDraft,state`). This grounds the rest of the session in the branch's actual history — reviewer feedback still to address, a merged PR meaning follow-up must restart from the trunk (see the system prompt's merged-PR rule), or a draft that `/finalize` will later land.

- **`mergeable` and `mergeStateStatus` are fetched as context, not as a work item.** They belong in the attach report, and they are the input `@.claude/skills/handle/SKILL.md` Step 2 reads — nothing here acts on them. So a `CONFLICTING` / `DIRTY` head is **reported**, and the Step 6 follow-up runs regardless. This fetch is where a conflicted head lands in front of an agent that has the host harness's "fix it now" rule loaded, which is why the negative is stated at all; CLAUDE.md § "Key principles" carries the general clause.

- **Note the PR's base ref while you're there.** `baseRefName` is the branch this work merges into, and it is not always the trunk — a project with promotion branches or long-lived feature branches will have PRs based elsewhere. Every follow-up you dispatch (`/finalize`, `/check-merge`, `/sync-branch`, free-form work) resolves the base from the PR itself, but state it explicitly when you hand off so nothing silently reverts to a `main` assumption.

- `/from-branch` is meant to be the **first** message of a session, so the branch you're currently on is essentially always the harness-created auto-branch — empty, unpushed work, exists only because the harness needed something to check out. Note its name and tip, which Step 4 writes into its command literally:

- **Sanity check** (don't trust the assumption blindly — verify there's no work to lose):

- If the count is `0` and the working tree is clean, proceed — the auto-branch is empty and will be discarded in Step 4.

- An untracked `docs/pr/<n>/` is the one thing that does not count as work to lose: `.claude/hooks/prompt-handle-pr-export.sh` writes it before the turn, on whatever branch HEAD was on, and `git checkout` carries it across to be committed there by `@.claude/skills/handle/SKILL.md` Step 2. Leave it and proceed.

- If the count is non-zero, or there are uncommitted changes, **stop and ask the user**. This shouldn't happen in normal `/from-branch` usage (the skill is meant for fresh sessions), so it's a signal that something is off — maybe the user invoked the skill mid-session after doing work, maybe the harness behavior changed. Don't auto-cherry-pick or auto-discard; surface the situation and let the user direct.

- `gh pr checkout <NNN>` is the most robust path when the input was a PR — it handles fork remotes, sets upstream, and leaves you on the PR head. Prefer it for PR inputs.

- Verify the result with `git branch --show-current` and `git log --oneline -3` — the head should match the PR/branch you intended, not the auto-branch.

- Delete the auto-branch on `origin`, where an empty branch is clutter every later branch list carries. The local ref needs nothing: it dies with the container.

- The delete is its own Bash call, with the branch name and the Step 2 SHA written out literally — never a variable, never chained after the checkout:

- The auto-mode classifier judges a command by its text, never by its output, so the Step 2 check proving the branch empty is invisible to it; a variable or a bare `--delete` reads as deleting a remote branch nobody named, which it blocks as Git Destructive. The lease is the proof it can read — git refuses with `stale info` unless the remote ref still sits on the SHA you checked — and a block on a separate call cannot take the attach down with it.

- Any refusal — `stale info`, a 403 from the session's git proxy, a classifier block — is reported and left for the operator; the attach stands. Don't retry it by another route: a 403 and a block are both policy answers.

- The session was launched with instructions to develop on the auto-branch (see the system prompt's "Git Development Branch Requirements"). That instruction is now stale. From this point on:

- State this explicitly in your turn output so the user can see the redirect took effect.

- - **No follow-up provided** → report the attach (current branch, last commit, PR link if applicable) in 1–2 sentences and stop. Wait for the user's next instruction.

- - **`go` / `implement` / `execute` follow-up** (the keyword optionally trailed by "the plan" / "plan" — nothing richer) → load `@.claude/skills/go/SKILL.md` and follow it from its Step 1; it owns locating the plan under `docs/plans/`, the plan-file lifecycle flip, and the closing hand-off to `/pr`. Do **not** inline-copy those steps. A `/from-branch` launch is already continued work, so there is no plan cycle to open — this follow-up **is** the go-ahead the lifecycle flip quotes. If the follow-up carries a real instruction beyond the keyword + that filler, it's a free-form follow-up — handle it as the bullet below instead.

- - **Free-form follow-up** → load `@.claude/skills/go/SKILL.md` and follow it via its § "Planless entry", treating the follow-up text as the task. Two points are `/from-branch`-specific:

- - **A concrete request is not a plan cycle.** `/from-branch` is continued work (CLAUDE.md § "Plan mode & questions in web sessions"), so routing through `/go` is not an invitation to write a plan file first.

- - **The quality passes are diff-scoped, so they self-limit.** A follow-up that produced no code ("explain why X fails", "rerun CI") leaves them nothing to act on, and each says so in its own "When to use". That is a property of the passes — "the change was small" is not grounds to skip them.

- - **Skill follow-up** (e.g. `finalize`, `check-merge`, `sync-branch`, or `test-on-gh` where the project has hydrated it) → load `@.claude/skills/<name>/SKILL.md` and follow it with the rest of the follow-up as its arguments. Do **not** inline-copy its steps; read and execute the actual file so updates to that skill flow through.

- - **Auto-branch is unexpectedly non-empty** (commits ahead of `origin/main`, uncommitted changes, detached HEAD) — Step 2 already stops on this. Don't try to recover automatically; ask the user.

- - **MCP says "not allowed"** for a branch/PR action — switch to `gh` (the token is in `GH_TOKEN`). Don't report the action as impossible.

- - **Branch was force-pushed since the PR was opened** — `git pull --ff-only` will refuse; do a `git reset --hard origin/<branch>` only after confirming with the user that there's no local work to lose.

- - **`go`/`implement`/`execute` given but `docs/plans/` has zero or multiple files** — don't guess; `@.claude/skills/go/SKILL.md` Step 1 owns the resolution, and Step 6 dispatches there.