|
|
@@ -1,32 +1,33 @@
|
|
|
---
|
|
|
name: "session-handoff"
|
|
|
-description: "Scrivere un HANDOFF.md di riassunto su richiesta dell'utente (on-demand) per passare il lavoro a un altro agente o a una nuova sessione, a qualunque punto del lavoro. Chiede sempre all'utente quali punti salienti esportare prima di scrivere il file."
|
|
|
+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."
|
|
|
---
|
|
|
|
|
|
## When to Use
|
|
|
-Quando l'utente lo richiede esplicitamente (es. "prepara un handoff", "scrivi l'handoff") o dichiara che il lavoro continuerà con un altro agente (nuova sessione pi, subagent, agente esterno). Non è vincolato a fine sessione o task: si usa a qualunque punto del lavoro, anche a metà di un task in corso.
|
|
|
+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.
|
|
|
|
|
|
## Procedure
|
|
|
-1. Confermare lo scopo dell'handoff: cosa dovrà fare il prossimo agente e quale stato serve per ripartire. Se invocato a metà lavoro, chiarire con l'utente lo scope: l'handoff copre il lavoro svolto finora, non necessariamente un task chiuso.
|
|
|
-2. Elencare all'utente i punti salienti candidati emersi dalla sessione (lavori completati, decisioni, file toccati, problemi aperti, prossimi passi) e chiedere quali esportare nell'handoff. Procedere alla scrittura solo dopo la conferma dell'utente.
|
|
|
-3. Scrivere HANDOFF.md nella root del progetto con struttura fissa: Obiettivo, Stato (fatto/in corso), Decisioni prese, File modificati/creati, Verifica, Problemi aperti, Prossimi passi, Comandi utili. Includere solo i punti confermati dall'utente; se una sezione non ha contenuti selezionati, scriverla vuota con nota "non applicabile".
|
|
|
-4. Per ogni file citato riportare solo path + motivo della modifica, non il contenuto. Usare puntatori (path, comandi, commit) invece del contenuto grezzo.
|
|
|
-5. Nella sezione Verifica riportare i comandi già eseguiti con esito (test/build/lint) ed eventuali errori noti o rischi aperti. Se il lavoro è in corso, segnare esplicitamente cosa non è ancora stato verificato.
|
|
|
-6. Passaggio all'altro agente: nuova sessione pi → pi -p "@HANDOFF.md Continua da qui: ..."; subagent → passare il path del file come istruzione; agente esterno → copia-incolla del markdown (il file è auto-contenuto).
|
|
|
-7. Se la sessione continua oltre il punto di handoff, aggiornare il file invece di crearne un secondo.
|
|
|
-8. Per renderlo ripetibile, riusare questo stesso template in ogni handoff successivo.
|
|
|
+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.
|
|
|
|
|
|
## Pitfalls
|
|
|
-- Non scrivere l'handoff senza aver prima chiesto e ottenuto dall'utente la lista dei punti salienti da esportare.
|
|
|
-- Non esportare l'intera trascrizione: il valore è il riassunto, non il log.
|
|
|
-- Non omettere stato di verifica e rischi aperti: sono ciò che serve davvero al prossimo agente.
|
|
|
-- Se l'handoff è generato a lavoro in corso, non presentare lo stato come completo: marcare chiaramente ciò che è a metà o non verificato.
|
|
|
-- Evitare summary vaghi tipo 'Fatto' o 'Ok': indicare esiti concreti e comandi eseguiti.
|
|
|
-- Non lasciare il file senza sezione Prossimi passi: deve essere eseguibile da un agente che parte da zero.
|
|
|
-- Attenzione al formato del file HANDOFF.md se l'agente di destinazione è esterno (es. niente sintassi specifica di pi).
|
|
|
+- 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).
|
|
|
|
|
|
## Verification
|
|
|
-1. Prima della scrittura è stata chiesta all'utente la selezione dei punti salienti e il file riflette la selezione ricevuta.
|
|
|
-2. HANDOFF.md esiste nella root del progetto e contiene tutte le sezioni previste.
|
|
|
-3. Un nuovo agente riesce a ripartire leggendo solo il file: i prossimi passi sono azionabili e i comandi citati esistono.
|
|
|
-4. I path dei file citati nell'handoff sono reali (verificare con ls/read).
|
|
|
+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).
|
