|
|
@@ -1,33 +1,14 @@
|
|
|
---
|
|
|
name: "session-handoff"
|
|
|
-description: "Write an on-demand HANDOFF.md summary, requested by the user, to hand the work off to another agent or a new session, at any point during the work. Always asks the user (via ask_user_question) which highlights to export before writing the file."
|
|
|
+description: Compact the current conversation into a handoff document for another agent to pick up.
|
|
|
---
|
|
|
|
|
|
-## When to Use
|
|
|
-When the user explicitly requests it (e.g. "prepare a handoff", "write the handoff") or states that the work will continue with another agent (new pi session, subagent, external agent). Not tied to the end of a session or task: it can be used at any point during the work, even midway through a task in progress.
|
|
|
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
|
|
|
|
|
|
-## Procedure
|
|
|
-1. Confirm the purpose of the handoff: what the next agent will have to do and which state is needed to resume. If invoked mid-work, clarify the scope with the user: the handoff covers the work done so far, not necessarily a closed task.
|
|
|
-2. List the candidate highlights that emerged from the session (completed work, decisions, files touched, open problems, next steps) and ask which ones to export in the handoff using ask_user_question: a structured multiSelect question with the candidate points as options (max 4 options per question; if there are more candidates, group them or use multiple questions). Proceed to writing only after the user's answer.
|
|
|
-3. Write HANDOFF.md in the project root with a fixed structure: Objective, Status (done/in progress), Decisions made, Files modified/created, Verification, Open problems, Next steps, Useful commands. Include only the points confirmed by the user; if a section has no selected content, write it empty with a "not applicable" note.
|
|
|
-4. For each file mentioned, report only path + reason for the change, not the content. Use pointers (paths, commands, commits) instead of raw content.
|
|
|
-5. In the Verification section, report the commands already executed with their outcome (test/build/lint) and any known errors or open risks. If the work is in progress, explicitly mark what has not yet been verified.
|
|
|
-6. Handoff to the other agent: new pi session → pi -p "@HANDOFF.md Continue from here: ..."; subagent → pass the file path as an instruction; external agent → copy-paste the markdown (the file is self-contained).
|
|
|
-7. If the session continues beyond the handoff point, update the file instead of creating a second one.
|
|
|
-8. To make it repeatable, reuse this same template in every subsequent handoff.
|
|
|
+Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.
|
|
|
|
|
|
-## Pitfalls
|
|
|
-- Do not write the handoff without first asking the user for and obtaining the list of highlights to export.
|
|
|
-- Do not collect the highlight selection as free text when ask_user_question is available: the structured question makes the selection explicit and traceable.
|
|
|
-- Do not export the entire transcript: the value is the summary, not the log.
|
|
|
-- Do not omit verification status and open risks: they are what the next agent really needs.
|
|
|
-- If the handoff is generated mid-work, do not present the status as complete: clearly mark what is halfway done or unverified.
|
|
|
-- Avoid vague summaries like 'Done' or 'Ok': state concrete outcomes and the commands executed.
|
|
|
-- Do not leave the file without a Next steps section: it must be executable by an agent starting from zero.
|
|
|
-- Pay attention to the HANDOFF.md format if the target agent is external (e.g. no pi-specific syntax).
|
|
|
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
|
|
|
|
|
|
-## Verification
|
|
|
-1. Before writing, the highlight selection was requested from the user via ask_user_question and the file reflects the selection received.
|
|
|
-2. HANDOFF.md exists in the project root and contains all the expected sections.
|
|
|
-3. A new agent can resume by reading only the file: the next steps are actionable and the referenced commands exist.
|
|
|
-4. The file paths mentioned in the handoff are real (verify with ls/read).
|
|
|
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
|
|
|
+
|
|
|
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
|
