Handoff — Workflow

Use the built-in prowl.handoff workflow to collect an agent-authored briefing, preserve durable context under .prowl/handoff/, and optionally launch a receiver.

Keywords:handoffhand offbriefingworkflow.prowl/handoffcurrent.mdcross-agentworkspace

Start a handoff#

Run the workflow from the source agent pane. With a receiver, select an enabled Agent Profile:

prowl workflow run prowl.handoff --role receiver=Codex --json

For a save-only handoff, no receiver is required:

prowl workflow run prowl.handoff --input next=save --json

The start response contains self_initiated.line. Follow that exact instruction and deliver a Markdown briefing with ## Objective, ## Current State, and ## Next Steps. A completed workflow confirms the packet was saved and, when requested, that the receiver was launched; it does not mean the receiver has finished the task.

The same workflow is available from the Agents popover, Active Agents context menu, Command Palette, and Settings › Agents › Workflows. Those entry points use the normal workflow start sheet and profile admission rather than a dedicated Handoff UI.

Durable packet#

builtin:save-handoff validates the briefing before changing shared state. It saves generated repository and source-session context beneath the runnable root:

<root>/.prowl/handoff/
  current.md
  context.md
  archive/workflow-<run UUID>.md
  sessions/

The receiver uses its immutable run-specific packet in archive/; later workflow runs can update current.md without changing that packet. Prowl creates a local .gitignore for this state. Keep secrets out of the briefing, and use the toolbar’s Workflow History to inspect the recorded run.

Retired CLI migration#

For one release, prowl handoff … returns HANDOFF_RETIRED without connecting to Prowl, writing artifacts, or starting an agent. Use the workflow commands above; the error repeats the receiver and save-only replacements so old scripts cannot silently perform a different operation.

Safety#

Saving reads repository state and does not commit, push, or execute destructive Git commands. A source pane must have a detected agent, and the receiver is launched only when the workflow selects that branch. Existing .prowl/handoff/ artifacts remain available to the workflow and history file actions.