/session-handoff kanban board

Install

Install just this, from a clone of the repo. Anything it needs comes with it.

./scripts/install-skills.sh --skill session-handoff   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill session-handoff   # Windows PowerShell

Needs: handoff-auto, kanban-setup, next (installed with it).

What it does

Ends an implementation session tied to a GitHub issue: writes the handoff document (via handoff-auto), adds a ## Board status section, and moves the issue's card to reflect reality.

When to use

• Wrapping up a session that started from an issue / board card.
• The implementer agent calls it to finish.

How to invoke

/session-handoff <issue number or URL>. Claude can also run it itself.

How it works

1. Calls handoff-auto with the issue as argument; takes the path it prints.

2. Appends ## Board status to that doc: issues/cards touched, complete / partial / blocked, deviations from the issue, new ideas found mid-session.

3. Moves the card (board lookup per next/BOARD.md).

   • Projects v2 via gh project item-edit with IDs looked up from gh project field-list / item-list (GraphQL fallback when the list is stale).
   • Label fallback creates status:in-review first if missing, then swaps status:in-progress → status:in-review when complete, otherwise leaves it and comments if blocked.
   • A Projects board with no In Review option: the card stays In Progress, the handoff says so, and it points at IN-REVIEW-OPTION.md.
   • Run by a guarded agent (implementer/manager, read-only gh), it skips the move and comment and lists them in the handoff for the caller.

4. Prints the handoff file path.

• Follows any handoff filename/section rules in the repo's CLAUDE.md/AGENTS.md.
• Commits the handoff only per handoff-auto/TRACKING.md: never on a fork, and in commit mode only when the current branch is the default.
• On a task branch it stays uncommitted on disk (update-progress commits it on the default branch), so it can't leak into the task's PR.

Flow

Card status flow: todo → in-progress → in-review → done.

• todo: set explicitly by gh project item-edit when an issue is added — item-add alone leaves Status empty.
• in-progress: set by pair or meta-orchestrator when they create the branch (their guarded agents can only read with gh).
• in-review: set by session-handoff.
• done: set by update-progress, once verified and merged; unmerged stays in-review.
• Label-mode status:* labels are created on first use (gh label create --color <hex> --force, colors in next/BOARD.md), not assumed to exist.

Design principles

• Record reality, not hope. Only a complete session moves the card to In Review. Complete means the issue's done-when is met: deviations are listed, and the done-when is not rewritten to fit. Partial or blocked work stays In Progress, and a blocked one gets an issue comment saying why.
• Wrap, don't duplicate. The document itself comes from handoff-auto; this skill only adds board status and the card move.
• Path last. The handoff path is the final line, so the implementer agent's caller can read it.

Shared context for these principles: Matt Pocock's video.

Use cases

• Ending a manual session that started from /next and an issue.
• The implementer agent's last step, so a manager or orchestrator gets a handoff whose path it can read.
• Stopping partway through a task: the board shows it is still In Progress, and the handoff says what is left.

Tips

• Pass the issue number (or URL) so the handoff and the card move target the right issue.
• Next, open a fresh session and run update-progress with the printed path; that is what verifies and closes the issue.
• Deviations listed under ## Board status are what update-progress later sends to consult-plan, so name them plainly in the session.
• A board error doesn't block: the handoff is still written and the error is noted.

Example

## Board status

- #31 Add CSV export: partial. Export works; tests for files over 1 GB missing.
- Deviation: used a streaming writer instead of building the file in memory.
- New idea: an `--gzip` option (not in the issue).

Related

• Next step: update-progress in a fresh session, with the printed path.
• Wraps handoff-auto; preloaded by the implementer agent.

Prereqs

• gh, authenticated with the project OAuth scope: run gh auth refresh -s project -s read:project once (see kanban/README.md).
• handoff-auto installed.

Sample workflows

• Close one session, start the next
  session-handoff → you → update-progress → next → you
  Install just this one: ./scripts/install-skills.sh --workflow close-the-loop or .\scripts\install-skills.ps1 -Workflow close-the-loop
• Wrap up a long session
  smartzone → divide → you → session-handoff → you
  Install just this one: ./scripts/install-skills.sh --workflow wrap-up-long-session or .\scripts\install-skills.ps1 -Workflow wrap-up-long-session

Source

• kanban/session-handoff/SKILL.md
• kanban/session-handoff/README.md