next-handoff-emit
When and how to emit handoff state (UserAsk / NextSuggestion / SessionReflection) to the graph during work, so the projected NEXT.md and per-user handoff stay current without agent discipline on a tra
SKILL.md.claude/skills/next-handoff-emit/SKILL.md
GitHubWhat I do
Tell the agent when to fire three small CLI calls during normal work,
so the user-graph nodes that drive .hero/next/<user>.md and the
field-grab CLI (hero next suggest, hero next ask,
hero next reflection) stay current — without writing to a
markdown file that the next checkpoint will clobber.
This skill replaces the "write the agent half of NEXT.md" pattern in
skills/next-md.md when next.projected is true. With
projection on, anything you write into NEXT.md gets wiped on the next
Stop hook. Emit structured events instead.
Why emit, not write
NEXT.md is a graph projection. Every Stop hook regenerates it from:
- Recent commits, AC flips, open features, blockers — derived from the project graph (no agent action needed).
- Last user ask, Suggested next prompt, Session reflections — attributed user-graph nodes, populated by the three commands below.
If you want something to survive into the next session's NEXT.md, it has to land as a graph node. The CLI is the one-liner way to do that.
The three commands
hero next ask "<text>"
Records a UserAsk node attributed to the current user. Singleton
per user — the latest supersedes prior. The projection renders this
as the "Last user ask" section.
Auto-emit: as of
next-auto-emit-user-ask, the end-of-turn Stop checkpoint (hero next checkpoint) automatically records the user's last transcript message as theUserAskwhenever the harness supplies atranscript_path(Claude Code does). So this command is now a manual override, not a per-turn requirement — fire it only when you want to record something other than the verbatim last message (e.g. a one-line paraphrase of a long, wandering prompt). Singleton supersession means your override cleanly replaces the auto-emitted node, and vice versa, with no duplicates.
When to fire:
- Every meaningful user prompt. Right after the user finishes asking for something concrete, before you start working on it.
- Quote the user's wording when short and direct. Paraphrase to one sentence when the prompt is long, conversational, or wandering.
- Skip when the user is making small talk, asking a clarifying question about your previous output, or otherwise not directing new work.
Examples:
hero next ask "Finish phase 4 of next-as-projection — wire UserHandoffMD into checkpoint"
hero next ask "Why does the test fail intermittently on the auth middleware?"
hero next ask "Let's try a different approach — instead of refactoring, just delete the dead branch"
The session goal — emit <!-- hero:goal: <one-line goal> -->
The handoff also captures the session's goal (the durable intent —
why the work is happening) as a separate SessionGoal node, distinct
from the volatile last-ask. The goal is captured automatically every
checkpoint from the transcript's opening messages — no command required.
You can sharpen it for free: once you understand the goal, emit it as a one-line HTML comment in your response —
<!-- hero:goal: add rate limiting to the login endpoint to stop credential-stuffing -->
The Stop-hook checkpoint greps your assistant messages for the last
such marker and records it as the session goal (priority marker, which
overrides the auto-derived opening-window goal but not a manual override).
It is invisible in rendered markdown, costs no extra call (it rides the
response you're already writing), and gives the next session model-quality
intent. Emit it once when the goal crystallizes, and again only if the
goal genuinely changes mid-session.
The marker is optional upside on top of the always-on window goal — if you never emit one, the floor still captures a reasonable goal from the opening exchange. Use it when the real intent isn't obvious from the first few messages (a session that opened with throat-clearing, or pivoted).
hero next goal "<text>" — the manual override
For the rare case where even the marker is wrong, hero next goal "<text>"
records a manual goal that supersedes every auto/marker goal. With no
argument it prints the current goal. This is a quality ceiling, not a
requirement — fire it only to correct a wrong auto-derived opener.
hero next goal # print current goal
hero next goal "stop credential-stuffing on the login endpoint"
Do not use hero next goal for the latest prompt — that is what
hero next ask owns. The goal is the session's durable WHY; the ask is
the most recent refinement.
hero next suggest "<text>"
Records a NextSuggestion node. Singleton per user. The projection
renders this as "Suggested next prompt" in the per-user handoff.
When to fire:
- At the end of a meaningful work unit (commit landed, phase shipped, blocker hit and parked). Phrase it as the user's next prompt, not as instructions to yourself.
- The bar: a fresh session pasting this verbatim should know immediately what to do.
Crucial framing — write in the user's voice:
| ❌ Wrong (agent-instructions voice) | ✅ Right (user-voice prompt) |
|---|---|
"Run hero next migrate-to-projection then ship phase 8" |
"run the migration and then we gotta do phase 8 right..." |
"Implement Phase 5 round-trip ingest with idempotency" |
"let's tackle phase 5 of next-as-projection, the round-trip" |
"Fix the auth middleware test" |
"why does the auth middleware test fail intermittently?" |
If genuinely no good next prompt exists (e.g. the user is about to make a strategic decision only they can make), don't emit — leave the field blank rather than fill it with noise.
hero next reflection "<text>"
Records a SessionReflection node. Multiple co-exist; the projection
shows the most recent N. The projection renders these as
"Recent reflections".
When to fire:
- When a non-obvious lesson surfaces — a constraint nobody told you, a gotcha you discovered, a surprising data point worth carrying into the next session.
- One sentence. Like a sticky note. The lesson, not the action.
- Skip mechanical observations — those land in commit messages or the project graph automatically.
Examples:
hero next reflection "config.Load reads from .hero/hero.json, not project root — silent no-op if you write to the wrong place"
hero next reflection "merge=ours plus stop-hook regen is cleaner than a custom merge driver for v1"
hero next reflection "MCP tool count is 35; README still says 25+"
Cadence
A normal session looks like:
| Event | Action |
|---|---|
| User sends a prompt that directs new work | hero next ask "..." |
| The session's real goal crystallizes | emit <!-- hero:goal: ... --> (once) |
| Phase / commit / meaningful unit lands | hero next suggest "..." |
| Surprise / lesson / gotcha surfaces | hero next reflection "..." |
| Conversation, clarification, or small question | nothing — let it pass |
| End of turn | the Stop hook handles the rest |
Aim for 1-2 emits per meaningful turn. Quality over quantity. A
single high-signal hero next ask and hero next suggest is better
than five vague ones.
What NOT to emit
- Don't fire
hero next askfor every user message — only when the intent actually shifts or a new ask arrives. - Don't
hero next suggestif the next move depends on the user making a decision only they can make. Leave it empty. - Don't reflect on mechanical observations the graph already captures (commits, AC status, blockers).
- Don't write to
.hero/NEXT.mddirectly when projection is on — it'll be wiped next turn. Use the commands. - Don't write scratch into
.hero/next/<user>.local.md. That file is machine-state-only and rebuilt wholesale on every checkpoint — anything outside the marker block is discarded (with a one-time backup to.local.md.bak.<timestamp>the first time hand-content is detected). For preserved per-machine notes the agent doesn't touch, use a path like.hero/notes/<user>.md.
Reading state
To check what's currently recorded:
hero next suggest # print suggested next prompt
hero next ask # print last user ask
hero next goal # print the session goal (durable intent)
hero next reflection # print recent reflections
hero next # full handoff (project + user + machine)
Add --json to any read for scripting; --copy to also copy to
clipboard; --user <slug> to read someone else's (in team mode).
Cross-machine continuity
The .hero/next/<user>.md file is the load-bearing artifact for
solo-no-Cloud cross-machine handoff. When you push from one machine
and pull on another, the next hero scan (or session-start) ingests
the file's content back into the local graph automatically.
This means the cadence above also gets you cross-machine continuity for free — emits on home laptop become readable on office desktop after a git pull, even with no Cloud configured.