| name | next-handoff-emit |
| description | 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 tracked file. |
| compatibility | opencode |
| metadata | {"audience":"any-agent","purpose":"session-handoff","applies_when":"next.projected = true (after `hero next migrate-to-projection`)"} |
What 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.
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"
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 "..." |
| 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 ask for every user message — only when the
intent actually shifts or a new ask arrives.
- Don't
hero next suggest if 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.md directly 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
hero next ask
hero next reflection
hero next
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.
