stacks-handoff

# Handoff For an explicitly requested handoff to a new worker, first produce the same portable summary, then dispatch it through the harness's native agent or chat tool when available. Creating a document alone does not start another chat. Avoid shell interpolation of the summary; pass it as structured prompt data. Track the worker's status and retain the source artifacts. The upstream `claude-handoff` variant is covered by this harness-neutral mode. See [NOTICE.md](NOTICE.md) and [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md). Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it to the OS temp directory, not the workspace: a handoff is scaffolding for one hop, and a stray `HANDOFF.md` in the repo is sediment. If the user passed an argument, treat it as a description of what the next session will focus on and tailor the document to that. Credit: adapted from Matt Pocock's `handoff` skill (MIT), <https://github.com/mattpocock/skills>. ## What goes in - **The goal**, in one paragraph. What the next session is trying to achieve. - **Where things stand.** What is done, what is in flight, what is untouched. - **The decisions already made, and why.** This is the part a summary of the diff cannot recover, so it is the part worth the most words. - **What is known to be broken or unverified.** Name the command that would prove it either way. - **Suggested skills.** Name which `stacks-*` skills the next agent should call the Skill tool for. A handoff that does not point at `stacks-orm` before a model change is handing over a landmine. - **Open questions** the next session has to resolve, or take back to the user. ## What stays out Do not duplicate content already captured elsewhere. Reference it by path, branch, URL or commit instead: - Committed code and its diff. - A spec, plan or ADR already written to disk. - An issue or PR on the tracker. - Anything a `stacks-*` skill already documents. Point at the skill. ## Redact before you write The document leaves this session, so treat it as publishable. Write `<REDACTED>` in place of: - Anything from `.env`, `.env.production` or `config/services.ts`. - `APP_KEY`, AWS keys, `HCLOUD_TOKEN`, registrar and DNS API tokens, database URLs with credentials in them. - Personal data pulled out of a database during the session. Reference the variable name and where it lives, never the value. ## Finish Tell the user the absolute path, and say in one line what the next session should do first. ## Before you hand off at all A handoff is narrow. It buys **portability**, and you only need it when something is actually travelling: a different agent, a different directory or repo, a colleague, or a side task forked mid-phase. If none of those apply, the cheaper moves are to continue, to clear, or to compact. `stacks-flow` has the ordered tree.