---
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."
---

## 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.

## 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.

## 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).

## 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).