name: handoff
description: "Save durable session handoff for a feature to WORKING.md plus history snapshot. Feature-first, safe."
metadata:
short-description: "Save session context (feature-first)"

handoff

Prepare a context handoff for the current feature.

Goals

• Produce an accurate, high-signal handoff.
• Keep a stable per-agent latest pointer and immutable history.

Paths

• .dev-docs/context/agents/<agent_id>/WORKING.md
• .dev-docs/context/agents/<agent_id>/history/<TS_FILE>--<TAG_SLUG>.md

Workflow

1) Universal preflight:
- git --version and git rev-parse --is-inside-work-tree (best-effort).
- Determine EFFECTIVE_MODE = git if both succeed, else local.

2) Resolve feature and mapping.
- Ensure TASKS exists.

3) Compute timestamps (UTC):
- TS_ISO: YYYY-MM-DDTHH:MM:SSZ
- TS_FILE: YYYY-MM-DDTHH-MM-SSZ

4) Choose TAG:
- Use user-provided tag if present.
- Else derive from TASKS Current Goal.

5) Ensure directories exist:
- .dev-docs/context/agents/<agent_id>/history/

6) Capture repo state (best-effort; use Unknown if not git):
- Branch, commit, status, diff stat.

7) Write snapshot and latest pointer using the template.

8) Optionally update history index.

Output

After writing the files, print EXACTLY these 3 lines and NOTHING ELSE:
? Context saved to .dev-docs/context/agents/<agent_id>/WORKING.md
?? Snapshot saved to .dev-docs/context/agents/<agent_id>/history/<TS_FILE>--<TAG_SLUG>.md
?? To resume: /mention .dev-docs/context/agents/<agent_id>/WORKING.md

Handoff file template

Session Context -

Current Session Overview

• Feature ID:
• Feature Name:
• Agent ID:
• Main Task/Feature:
• Current Status:
• Last Known Good State:

Repo Snapshot

• Branch:
• Commit:
• Dirty Working Tree:
• git status --porcelain:
• git diff --stat:

Progress vs Tasks

• Completed:
• In Progress:
• Next Steps (priority order):

Running / Testing

• Commands run:
• Known Issues / Gotchas:

Resume Checklist

• [ ] /mention .dev-docs/context/agents/<agent_id>/WORKING.md
• [ ] Review git status and git diff
• [ ] Run checks from .dev-docs/commands.md
• [ ] Start with "Next Steps #1"