handoff

name	handoff
description	Use when the user wants to pass current task context to another AI agent (Gemini, Qwen, etc.) so they can continue mid-thought. Writes a structured baton-pass to ~/.ai-shared/handoffs/. Triggered explicitly via /handoff [to].

handoff — Drop Context for Another Agent

Mental model

A handoff is a drop, not a send. We leave a markdown note in a shared inbox (~/.ai-shared/handoffs/); whoever picks it up reads it and continues. There is no recipient who must receive — there is a slot where the next agent looks. Use to / for / picker / who picks it up. Do not say target, recipient, destination address. The metaphor is a baton on a table, not a packet on a wire.

Overview

A handoff is an explicit, user-initiated baton-pass from this session to another agent. It writes a single markdown file under ~/.ai-shared/handoffs/ containing the active task, current state, next step, open questions, and any pointers the next agent needs to continue without forcing the user to re-explain.

The full protocol — file naming, frontmatter schema, status lifecycle — lives in ~/.ai-shared/AGENTS.md under "Cross-Agent Handoff Protocol". This skill is the write side. The read side is /pickup.

When to Use

• User says "handoff to gemini", "/handoff", "pass this to qwen", "let gemini take over".
• User explicitly switches agents mid-task and wants continuity.

Do NOT use when:

• The task is finished — there's nothing to hand off.
• The user is just asking a one-shot question of another agent (use the agent's CLI directly).
• No real context exists yet (fresh session, no decisions made) — say so and ask what to record.

Arguments

/handoff [to] — to is a short agent ID: claude, gemini, qwen, etc. It's a label on the slot, not a recipient address.

Default to: claude. Most handoffs are the user changing working directory or starting a fresh Claude session to continue the same task. Only use gemini / qwen / etc. when the user explicitly names one. Never ask "for whom?" — pick claude and let the user redirect.

Workflow

1. Resolve     to = arg or "claude"; from = "claude-<model-suffix>"
2. Gather      Synthesize from current conversation:
                 - Task: one paragraph, what + why
                 - Files touched: scan recent edits + git status if in a repo
                 - Worktrees: `git -C /etc/nixos/mandragora worktree list` (or "none")
                 - Rebuild status: green / dirty / not attempted
                 - Next step: literal next action
                 - Open questions
                 - Pointers: file:line references that matter
3. Write       Path: ~/.ai-shared/handoffs/<UTC-ISO>-claude-to-<to>.md
                 Timestamp format: YYYYMMDDTHHMMSSZ (no separators, sorts lexically)
                 Frontmatter: status: open
                 Write immediately. No draft-then-ack step — user invoked
                 /handoff to offload context, not to review a draft. Use the
                 gathered state directly.
4. Confirm     Tell the user the path with a one-line summary so they can
                 spot obvious mistakes and ask for a follow-up handoff.

File Format

Match the schema in ~/.ai-shared/AGENTS.md exactly. Example:

---
from: claude-opus-4-7
to: gemini
project: /etc/nixos/mandragora
created: 2026-04-26T14:32:00Z
status: open
consumed_at:
---

## Task
We're tightening hyprland border colors after the 0.54 update broke
the inactive border alpha. The fix is in modules/desktop/hyprland.nix
but a layerrule snippet still references the old color name.

## State
- Files touched: modules/desktop/hyprland.nix, .config/hypr/extra.conf
- Worktrees: none
- Rebuild status: dirty (edits not yet rebuilt)

## Next step
Update the `layerrule` block in .config/hypr/extra.conf line 47 to use
`col.inactive_border` instead of the deprecated `inactive_border_color`,
then run `mandragora-switch` and verify with `hyprctl configerrors`.

## Open questions
- Should `col.active_border` get the same alpha treatment, or keep it solid?

## Pointers
- modules/desktop/hyprland.nix:112 — color decl
- .config/hypr/extra.conf:47 — the stale reference

Writing the Timestamp

ts=$(date -u +%Y%m%dT%H%M%SZ)
to=${1:-claude}
path=~/.ai-shared/handoffs/${ts}-claude-to-${to}.md
mkdir -p ~/.ai-shared/handoffs
# write the file with the Write tool, not heredoc

The created: field inside the frontmatter is the same instant in standard ISO format (date -u +%Y-%m-%dT%H:%M:%SZ).

Critical Rules

1. Write immediately, no draft-ack. The user invoked /handoff to offload context, not to babysit a review loop. Gather state, write the file, report the path. If the user spots a mistake they ask for a follow-up handoff.
2. Ground everything in current state, not memory. Run git status, git worktree list, etc. before claiming "files touched" or "worktrees". A handoff that lies about state is worse than no handoff.
3. Be specific in "Next step". "Continue the work" is useless. Name the file, the line, the command.
4. Don't include secrets. Never paste secrets/ contents, env tokens, or credentials. Reference paths only.
5. Don't delete or edit existing handoffs. Append-only. If a handoff was wrong, write a new one that supersedes it (and say so in the Task paragraph).
6. Never auto-handoff. Only on explicit /handoff invocation.

Hand-Off

After writing, report to the user:

Wrote handoff: ~/.ai-shared/handoffs/<filename>
  to: <to>
  task: <one-line summary>
Whoever picks it up runs /pickup to claim it.

Then stop. Do not switch agents yourself.