next-md

Maintains the agent half of NEXT.md session handoff briefings across solo and team modes.

Updated Apr 20, 2026
One-click install
npx skills add https://github.com/astroville/sprout --skill next-md-astroville
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: next-md
Source: https://github.com/astroville/sprout/tree/main/.claude/skills/next-md
Command: npx skills add https://github.com/astroville/sprout --skill next-md-astroville

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When an AI coding session ends or gets compacted, the next session loses all context about what the user wanted, what shipped, and what was already tried. This Skill defines the format and quality bar for NEXT.md, a living handoff briefing that lets a fresh session resume work without asking "what were we doing?" ## Core Features & Use Cases - Structured handoff format: Defines the agent-written half of NEXT.md (Last user ask, Just finished, Next, Blocked on, Tried and failed, Context, Proposed next ask) above a machine-maintained state block. - Solo and team modes: Supports a single shared .hero/NEXT.md or per-user briefings under .hero/next/<user>.md with a shared team roster and updates section. - Update discipline rules: Specifies exactly when to overwrite the agent half (intent shifts, blockers, rejected approaches) versus leaving it alone, with a 15-40 line target and 60-line hard cap. - Use Case: After a long debugging session, the agent updates NEXT.md with the real error message, the two approaches that failed, and a runnable next step, so tomorrow's session resumes productively in one read. ## Quick Start Ask the agent to read the current NEXT.md via hero next path and update the handoff briefing with what was just finished and what comes next.

Frequently Asked Questions about next-md

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I hand off context between AI coding sessions?▼

Write a NEXT.md briefing with sections for the last user ask, what just finished, the next step with a runnable pointer, blockers, and failed approaches. A fresh session reads this file first and resumes without asking what you were doing.

What should a session handoff document contain?▼

Include the user's last request in their own words, what shipped with commit references, a concrete next step, actual error messages for blockers, and one line per rejected approach. Keep it between 15 and 40 lines and point at artifacts instead of pasting code.

When should the agent update the handoff file?▼

Update only when a fresh session could no longer pick up correctly from the current file: the user's intent shifted, work shipped, a blocker appeared or resolved, or an approach was rejected. Conversational turns and new commits alone do not require an update.

Can I hand-edit the machine state section of NEXT.md?▼

No. The block between the BEGIN and END HERO MACHINE STATE markers is rewritten by the Stop hook on every turn, and any hand-written content there is wiped. The same applies to the per-machine .hero/next/<user>.local.md file.

How does team mode differ from solo mode for session handoffs?▼

In team mode each user writes a personal briefing at .hero/next/<user>.md instead of the shared .hero/NEXT.md. The shared file becomes a roster where you update your one-liner status, plus occasional updates only when something affects teammates.

What happens if next.projected is enabled in hero.json?▼

When next.projected is true, NEXT.md is graph-projected and anything hand-written to it is wiped on the next Stop hook. Use the next-handoff-emit skill instead of this legacy workflow.