Handoff — Sistema di Knowledge Base Persistente

Questo sistema mantiene tutta la memoria del progetto nella cartella .handoff/, strutturata per permettere a qualsiasi agente AI (o operatore umano) di riprendere il lavoro senza perdere contesto tra sessioni.

Struttura della cartella .handoff/

.handoff/
├── HANDOFF-001.md       ← prima sessione
├── HANDOFF-002.md       ← seconda sessione (legge il precedente)
├── HANDOFF-NNN.md       ← sessione corrente (sempre il numero più alto)
├── CLAUDE.md            ← istruzioni persistenti per Claude Code
├── PROMPTS.md           ← libreria prompt riutilizzabili
├── CLIENTS.md           ← schede clienti attivi
└── WORKFLOW.md          ← metodologia TheNewA(i)telier

Regola fondamentale: gli HANDOFF-NNN.md sono append-only — non si modificano mai le sessioni passate. Si aggiorna solo creando un nuovo file numerato.

Comandi riconosciuti

Workflow A — INIT (primo avvio su un progetto)

Eseguire quando .handoff/ non esiste ancora.

Step 1 — Crea la struttura

mkdir -p .handoff

Step 2 — Crea i documenti persistenti con scaffolding

Leggere references/init-templates.md per i template di partenza di ciascun file (CLAUDE.md, PROMPTS.md, CLIENTS.md, WORKFLOW.md). Creare tutti e 4 nella cartella .handoff/ con il contenuto scaffold appropriato al progetto rilevato dal contesto della conversazione.

Step 3 — Crea il primo HANDOFF-001.md

Seguire il Workflow B (SAVE) per creare HANDOFF-001.md con le informazioni disponibili al momento dell'init.

Step 4 — Aggiungi .handoff/ al progetto

Se esiste un .gitignore, suggerire all'utente se vuole committare .handoff/ o escluderlo. Raccomandazione: committarlo — è documentazione di progetto.

Workflow B — SAVE (crea nuovo handoff)

Step 1 — Determina il numero progressivo

ls .handoff/HANDOFF-*.md 2>/dev/null | sort | tail -1

Se non esiste nessun file → creare HANDOFF-001.md. Se esiste l'ultimo → incrementare di 1 (es. HANDOFF-007.md → HANDOFF-008.md).

Step 2 — Leggi l'ultimo handoff (se esiste)

Prima di scrivere, leggere l'ultimo HANDOFF-NNN.md per capire cosa era in sospeso e non contraddire la storia. I Next Steps dell'handoff precedente diventano la base della sezione Current Progress del nuovo.

Step 3 — Scrivi il nuovo HANDOFF-NNN.md

Usare la struttura esatta in references/handoff-template.md. Le 5 sezioni obbligatorie sono:

1. 🎯 Goal — Obiettivo finale del progetto (stabile tra sessioni).
2. ✅ Current Progress — Checklist di fatto/non fatto con nomi file specifici.
3. 💡 What Worked — Approcci vincenti con dettaglio tecnico esatto (prompt, parametri, comandi). Il perché conta quanto il cosa.
4. ❌ What Didn't Work — Errori e vicoli ciechi. Mai lasciare vuota: salva tempo al prossimo agente. Se davvero nulla è fallito: "Nessun vicolo cieco rilevante."
5. 🚀 Next Steps — Lista numerata, concreta, azionabile. Item #1 eseguibile subito senza domande.

Regole di scrittura:

• Lingua del contenuto = lingua della conversazione (italiano se l'utente parla italiano)
• Titoli sezioni in inglese (portabilità cross-tool)
• Contenuto estratto dalla conversazione reale, mai generici
• Zero segreti (API key, password, token): referenziarli come "→ vedi .env"

Step 4 — Quality check

Prima di finalizzare:

• Tutte 5 le sezioni compilate con contenuto reale
• Header metadata con data, sessione, operatore
• Next Steps numerati e il primo è eseguibile senza domande
• Nessuna credenziale nel testo

Step 5 — Notifica

Comunicare il path esatto del file creato e come riprendere:

✅ Salvato: .handoff/HANDOFF-003.md

Per riprendere in una nuova sessione Claude Code:
→ claude (apri una nuova sessione)
→ "Leggi .handoff/HANDOFF-003.md e riprendi da dove eravamo"

Workflow C — LOAD (ripresa da sessione precedente)

Step 1 — Trova l'ultimo handoff

ls .handoff/HANDOFF-*.md | sort | tail -1

Step 2 — Leggi in ordine

1. Leggi l'ultimo HANDOFF-NNN.md completamente.
2. Leggi .handoff/CLAUDE.md — contiene istruzioni operative persistenti.
3. Se qualcosa è ambiguo, leggi il penultimo handoff. Non leggere tutta la chain di default.

Step 3 — Conferma comprensione

Rispondi in 3-4 righe: obiettivo, punto di avanzamento, prossima azione. Non recitare il documento — dimostrare di aver capito.

Step 4 — Parti dal Next Step #1

Esegui subito il primo passo. Non re-interrogare l'utente su cose già documentate nell'handoff. Tratta What Didn't Work come vincoli rigidi: non riprovare approcci già falliti salvo istruzione esplicita dell'utente.

Workflow D — UPDATE DOCS

Quando l'utente vuole aggiornare uno dei documenti persistenti:

• CLAUDE.md — nuove istruzioni operative, preferenze di stile, regole del progetto
• PROMPTS.md — aggiungere prompt validati dalla sessione corrente
• CLIENTS.md — aggiornare scheda cliente, aggiungere nuovo cliente
• WORKFLOW.md — aggiornare la metodologia

Leggere prima il file esistente, fare un update chirurgico (non riscrivere da zero), e confermare le righe modificate/aggiunte all'utente.

Workflow E — Install proactive context-warning hook (Claude Code, opzionale)

Esegui una sola volta per progetto, su richiesta dell'utente o durante spec-as-source-setup. Installa un hook reale PreCompact che avvisa automaticamente prima che Claude Code compatti il contesto (cioè quando il contesto si avvicina davvero al limite) — il trigger deterministico più vicino a "contesto vicino a 300k" disponibile oggi in Claude Code. Per ambienti/agenti diversi da Claude Code, vale solo la rule soft handoff-suggestion (non richiede installazione).

Step 1 — Leggi l'eventuale .claude/settings.json esistente

test -f .claude/settings.json && cat .claude/settings.json || echo "(non esiste ancora)"

Step 2 — Fondi l'hook, non sovrascrivere

Leggi templates/claude-settings-hooks.json in questa skill. Se .claude/settings.json non esiste, crealo con esattamente quel contenuto. Se esiste già:

• se non ha la chiave hooks.PreCompact, aggiungi l'intero blocco PreCompact da templates/claude-settings-hooks.json;
• se ha già hooks.PreCompact, appendi l'oggetto hook del template all'array esistente — non sostituire gli hook già presenti.

Non scrivere mai un .claude/settings.json che cancelli configurazione preesistente (altri hook, permessi, ecc.).

Step 3 — Conferma

cat .claude/settings.json

Riporta all'utente: "Hook PreCompact installato — riceverai un avviso prima di ogni compattazione automatica del contesto."

Note per Claude Code

• In Claude Code, usa bash per creare/leggere file .handoff/ direttamente nel filesystem del progetto.
• Il file .handoff/CLAUDE.md può essere aggiunto al contesto di Claude Code come file sempre caricato (con @.handoff/CLAUDE.md all'inizio della sessione).
• Questa skill è bundled in questo plugin (skills/handoff/); se installata anche globalmente in ~/.claude/skills/handoff/, le due copie sono indipendenti — aggiornarle separatamente.
• Se .handoff/ non esiste e l'utente chiede di salvare, offrire di fare init prima.
• Il contesto si avvicina al limite (compattazione imminente)? Suggerire subito /handoff save, anche senza che l'utente lo chieda — vedi la rule handoff-suggestion per il trigger automatico.