Handoff Agent Skill

Handoff

Operator interface for two-session execution: one session plans (session=two at the Step 0 gate), a second

session in another environment builds, and the first session reviews. The lifecycle and package format are defined

in ../hyperflow/session-handoff.md; this skill is the thin set of verbs over it

(mirrors how /hyperflow:flush fronts the deferred-commit machinery).

Packages live at .hyperflow-handoff/<slug>/ (committed, so they travel via git). STATUS (`planned → built →

reviewed`) is the single source of truth and decides which side of the handoff you are on.

Subcommands

list

Read-only. List every .hyperflow-handoff/*/ (excluding .archive/): slug · STATUS · on_complete · age. Group

by status so the user sees what is awaiting build vs awaiting review.

status [<slug>]

Show the HANDOFF.md manifest + STATUS for one package (or all). When STATUS=built, also print the

COMPLETION.md diff range and commit count. Read-only.

pickup <slug> — build side

Thin alias for starting the second-session build: invoke Skill with skill: dispatch and args: "<slug>".

Dispatch's Step 1.0 rehydrates artefact/ into .hyperflow/, runs /hyperflow:scaffold if the cache is missing,

builds the batches, writes COMPLETION.md + STATUS=built, and then deploys or stops per on_complete.

review <slug> — planning side

• Require STATUS=built (else: "handoff <slug> is <status> — nothing to review yet").
• Read COMPLETION.md → extract Diff range = <base>..<head>.
• Invoke Skill with skill: audit and args: "<base>..<head> level=3" (level=5 when the originating triage

flow in HANDOFF.md was scientific or security). The audit dispatches the matching domain specialist

reviewers over the second session's diff.

• On audit clean pass → fire the deploy gate (AskUserQuestion — Run /hyperflow:deploy? Yes / No, binary, no

marker). On NEEDS_FIX → the audit fix-gate (Yes → /hyperflow:plan → /hyperflow:dispatch) handles it.

• Set STATUS=reviewed once the review is accepted.

complete <slug>

Mark the lifecycle done: set STATUS=reviewed (if not already) and archive the package to

.hyperflow-handoff/.archive/<slug>/. Commit chore(handoff): archive <slug>.

Resolution

• Default <slug> = the most-recently-modified package when omitted from status/pickup/review.
• A package whose STATUS=planned is a build-side task (run pickup); built is a review-side task (run

review). The session-start hook surfaces the right verb automatically.

Iron rules

• Never edit the build's commits. review is read-only over the diff range; fixes flow through the audit

fix-gate → scope → dispatch, never by amending the second session's commits.

• Never force-push; never --no-verify. Auto-push failures surface the exact git push -u origin <branch>.
• No AI attribution in any commit or package file.
• Honors handoff.* config (autoPush, remote, packageDir).

Doctrine

Shared rules in ../hyperflow/DOCTRINE.md. Package contract + templates in

../hyperflow/session-handoff.md.