pm-handoff

What this skill does

# PM Handoff

## Cross-team handoff context (v0.21.0+)

When `--scope team:<KEY>[+subteams]` is passed (or the handoff naturally spans more than one team), pull the in-scope issues with `scope-briefing` before drafting the brief. Use the result to populate "Recent work" and "What's not done" with concrete issue IDs rather than vague references.

```bash
node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-cache.js" scope-briefing --scope "team:ENG+subteams"
```

The four-block invariant (summary, done + how to use, NOT done + next steps, open questions) still applies — scope just gives you more accurate raw material to fill the blocks.

Produce a recipient-facing brief that moves work forward — either to another teammate (cross-person handoff) or to the next phase of the lifecycle (cross-stage handoff). The brief packages what's done, how to use it, what's NOT done, and what's open, then routes through configured channels.

This skill is **downstream** of every other pm-* skill that creates state. It's how work leaves your hands cleanly.

## The load-bearing claim

A handoff is **not** a status update. The CLI refuses to ship a brief whose "What's not done — next steps" block is empty. If there's nothing outstanding, you're not handing off — you're celebrating. Use **pm-report** for that. There is no `--force` to override this; either fill the block or ship through a different skill.

## Two modes

| Mode | When to use | Default detection |
|---|---|---|
| `person` | "Hand this off to Alex", "I'm OOO Friday", "passing this to <name>" | Trigger phrase names a teammate |
| `stage`  | "Ready for release", "ready for QA", "deploy handoff" | Trigger phrase names a lifecycle stage |

Auto-detected from the prompt. Override with `--mode person|stage`. For stage mode, the first-class transition is `--from pr --to release`. Other transitions use the generic template (`stage-generic.md`).

## Project configuration

The skill reads two fields from `<repo>/.claude/pm/project.json`:

- **`handoff_channels`** — array of destinations. Each entry has `type` (`linear` / `github` / `markdown` / `chat`) plus per-type config. At least one channel required.
- **`handoff_templates`** — optional map of `<mode>` or `<mode>:<from>-><to>` keys to template names. Falls back to bundled defaults.

Get the resolved config:

```bash
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" config --slug "<slug>"
```

Missing config → guided error pointing at `/pm-setup`. No silent defaults.

## Workflow

### Step 1: Capture state (scaffolding only)

```bash
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" capture \
  --slug <slug> --mode person --to alex
```

Or for stage mode:

```bash
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" capture \
  --slug <slug> --mode stage --from pr --to release --prs 247,251
```

What gets captured: issue metadata from pm-cache, current branch, commits since main divergence, files touched, PR list, heuristic checklist from the issue body. **Not captured:** "what I tried", "why I decided X", "what's tricky about this." That's your job in Step 2.

The CLI writes a draft JSON state object to a temp file and returns its path.

### Step 2: Draft the brief

```bash
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" draft \
  --slug <slug> --state-file <path-from-step-1>
```

The CLI resolves the template (three-scope: per-project → user → bundled), substitutes `{{var}}` placeholders against the state, and writes a brief to a temp file.

**This is where you do the heavy lifting.** Open the brief in an editor. Fill the four required blocks with prose that's actually useful to the recipient. The bundled templates have inline `> **Operator action:** ...` prompts marking each block — replace them.

For the narrative parts ("how to use it", "what's not done", decisions), **re-read the session transcript and the relevant issue/PR comments**. The CLI cannot extract those for you.

When you save, the brief is ready for `send`. If "What's not done" is empty, the next step will reject it with `EMPTY_NOT_DONE`.

### Stuck-lens integration

When building "What's NOT done" entries, `pm-handoff` invokes `report-lenses.stuck` (`hooks/lib/report-lenses.js`) and annotates each issue with its stuck reasons (`stale`, `no_update`, `blocked_label`, `unassigned_p1_p0`, `needs_info_self`). The recipient sees not just what's open but why it's drifting.

### Step 3: Send

```bash
# Dry-run — shows the per-channel plan
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" send \
  --slug <slug> --brief <path-from-step-2>

# Apply
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" send \
  --slug <slug> --brief <path-from-step-2> --yes
```

The send verb fans out to every configured channel. Each reports independently — if Linear succeeds and the GitHub reviewer-request fails, the result shows per-channel status (`sent`, `partial`, `failed`, `already_sent`).

Use `--only <channel-type>` to scope to one channel (e.g., `--only markdown` to write the file without posting to Linear).

**Idempotency:** every brief has a content hash. Re-running `send` on the same brief is a no-op (markdown file already exists with matching hash, Linear comment already posted, etc.). Use `--force` to override.

### Step 4 (chat channel only): Hand off to resend-cli

The `chat` channel doesn't deliver email itself — it returns a payload (subject, to, body) and points at the `resend-cli` skill via `next_skill`. The operator picks that up and invokes `resend-cli` to actually send.

### Step 5: Audit later

```bash
node "$CLAUDE_PLUGIN_ROOT/skills/pm-handoff/scripts/pm-handoff.js" list --slug <slug>
```

Lists past handoffs in `docs/pm/handoffs/` sorted newest-first with date, recipient, and content hash. Useful when reviewing what's been sent over the last week.

## Channels

### Markdown
Writes the brief to `<channel.path>/<YYYY-MM-DD>-<slug>-to-<recipient>.md`. The file is `git add`-ed; the operator commits it. The brief is version-controlled in the repo for the audit trail.

### Linear
Posts the brief as a comment on the linked Linear issue (or appends to the issue body if `linear comment create` is unsupported in the installed CLI version — the probe runs lazily at send-time). Updates assignee + state per channel config (`assignee_from: "recipient"` + `default_status: "In Review"`).

### GitHub
Posts the brief as an issue/PR comment via `gh issue comment`. Optionally `gh pr edit --add-reviewer <recipient>` (when `request_review: true`) and `gh pr ready` (when `ready_for_review: true`).

### Chat (resend-cli handoff)
Returns a payload. The operator invokes `resend-cli` separately to deliver. Project must have `.resend.md` configured.

## Proactive invocation

Use this skill proactively when:
- pm-status reports stale issues (`stale_issues` non-empty) — offer to write a handoff for one of them
- A PR merges and `handoff_channels` includes a release-style destination — offer to write the release handoff
- A branch has been inactive 3+ days with no PR — offer to write a handoff for whoever's covering

## Failure codes

| Code | Meaning | Operator action |
|---|---|---|
| `NO_HANDOFF_CONFIG` | Project has no `handoff_channels` | `/pm-setup` to add |
| `NO_CONTEXT` | Auto-capture found no branch/issue/PRs | Pass `--issue` or `--prs` explicitly |
| `MISSING_BLOCK` | Brief is missing one of the four required blocks | Edit the brief, restore the block |
| `EMPTY_NOT_DONE` | "What's not done" block is empty | Fill it, or use pm-report instead |
| `TEMPLATE_NOT_FOUND` | Named template missing in all three scopes | Check `handoff_templates` or use a bundled name |
| Per-channel `failed` / `partial` | A channel failed during send | Inspect `error` field; retry with `--only <channel>` and `--force` |

## References

- [Design spec](../../../../docs/superpowers/specs/2026-05-11-pm-handoff-design.md) — full architectural rationale
- [Examp