feat(handoff): add 'flow handoff <slug>' command#495
Merged
Conversation
Implements the protocol proposed in docs/planning/PROPOSAL-claude-chat-to-code-handoff.md. - lib/handoff-helpers.zsh: _flow_handoff() scaffolds docs/planning/HANDOFF-<slug>.md from a fixed schema (Summary, Key Decisions, Traps to Avoid, Working Agreements, Relevant Files, Open Work, Verification Note, Origin) - Relevant Files pre-filled from 'git diff --name-only' against base branch (default dev, falls back to main) - Refuses to overwrite an existing handoff for the same slug - --issue flag files a GitHub issue via gh CLI using the handoff as the body - Wired into commands/flow.zsh dispatcher and completions/_flow - docs/commands/handoff.md command reference + mkdocs.yml nav entry - CHANGELOG.md entry under Unreleased Tests: - tests/e2e-handoff.zsh: 7 tests against an isolated temp repo (help, fresh slug, overwrite refusal, real-diff pre-fill, empty-diff placeholder, --issue-without-gh failure, and a zsh -f regression test for a stray-stdout bug hit during prototyping) - all passing - tests/dogfood-handoff.zsh: real-repo smoke test, self-cleaning artifact - passing Fixes a zsh special-variable collision found during prototyping (local var named 'fpath' collides with zsh's function-autoload array) by using git diff --name-only instead of parsing --stat output.
Data-Wise
pushed a commit
that referenced
this pull request
Jul 7, 2026
PR #495 shipped the command but missed the usual doc surfaces (QUICK- REFERENCE.md, flow.1, MASTER-API-REFERENCE.md), and its own docs/commands/handoff.md linked to docs/specs/ which mkdocs excludes from the built site. - man/man1/flow.1: add handoff to Setup & Diagnostics + an example - docs/help/QUICK-REFERENCE.md: add Session Handoff section - docs/reference/MASTER-API-REFERENCE.md: add Handoff Helpers section - mkdocs.yml: exclude the planning proposal doc from nav (working doc, like the ADHD templates) - docs/commands/handoff.md: point the spec link at GitHub instead of the excluded specs/ path Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JnVugoVjTHRK41krTTMi8L
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
flow handoff <slug>, scaffolding a structureddocs/planning/HANDOFF-<slug>.mdfor transferring context between Claude chat/planning sessions and Claude Code sessions (or across a context reset).git diff --name-onlyagainst a base branch, refuses to overwrite an existing handoff, and can file a GitHub issue (--issue) from the same content.flowdispatcher and completions; command reference + spec + proposal docs included.Test plan
tests/e2e-handoff.zsh(7 tests) +tests/dogfood-handoff.zsh— all passing.