05_update_breadcrumbs_skill

Overview

This skill updates and preserves intent breadcrumbs so agents retain context across sessions. It creates or updates a human-readable NEXT.md and a machine-readable STATE.json at the workspace root to record status, objective, next steps, and blockers. The goal is to provide a deterministic checkpoint that agents and humans can read and act on.

How this skill works

The skill accepts parameters for status, objective, next steps, and blockers and writes them into two artifacts: NEXT.md (appendable human notes) and STATE.json (validated JSON). It preserves existing NEXT.md content by appending or performing smart replacements, and it validates JSON syntax before saving STATE.json to avoid corruption. It runs from the workspace root and returns the updated file paths and a success/failure result.

When to use it

• Before pausing or ending an agent session to capture next actions
• When an agent hits an impasse or blocker and needs to record context
• To checkpoint progress between automated runs or handoffs
• Prior to shifting work to another agent or human collaborator
• When you want an auditable, deterministic record of intent and state

Best practices

• Run from the workspace root so files are created in a predictable location
• Prefer appending human notes to NEXT.md rather than overwriting; include timestamps
• Keep STATE.json concise and machine-friendly: status, objective, nextSteps, blockers
• Validate status values (active, blocked, paused) to keep state consistent
• Treat NEXT.md as README-adjacent context for humans; keep details actionable

Example use cases

• Agent finishes a sprint task and saves next steps and blockers before stopping
• Automated test runner records failure context and prioritized next actions
• Handoff from one developer to another with a clear, machine-readable state
• Long-running investigation logs interim status and unresolved blockers
• Periodic checkpoints during multi-step workflows for recoverability