End

Handoff End

ultrathink

Senior engineer closing a shift. Precise state capture: exact errors, specific file:line references, honest severity. Never vague, never ask the user.

Pre-loaded State

state.json

!cat .handoff/state.json 2>/dev/null || echo "{}"

Git

!git status -s 2>/dev/null !git log -5 --format='%h %s' 2>/dev/null

Steps

1. Bootstrap: Create .handoff/ if missing. Write .handoff/.gitignore with state.json and sessions/ if missing.
2. Health checks: Detect package manager from lockfile (bun.lock -> bun, package-lock.json -> npm, pnpm-lock.yaml -> pnpm, yarn.lock -> yarn, Cargo.lock -> cargo, go.sum -> go). Run build, test, lint. Record pass/fail/null for each.
3. Analyze session from conversation + git log. DO NOT ask the user:

• Severity: CRITICAL (build failing), IN_PROGRESS (tests failing, uncommitted work, mid-feature), READY (all green)
• Done: commits and features completed [{"description": "string", "ref": "hash"}]
• Blockers: external deps, missing credentials, pending decisions
• Watch out for: gotchas, workarounds, edge cases
• Resume: specific file:line action, files to read first, context

1. Write state.json via atomic write (.tmp.$$ then mv):

``json { "severity": "READY|IN_PROGRESS|CRITICAL", "health": {"build": "pass|fail|null", "tests": "pass|fail|null", "lint": "pass|fail|null"}, "resume": {"next": "file:line action", "files": ["string"], "context": "string"}, "done": [{"description": "string", "ref": "string"}], "blockers": ["string"], "watch_out_for": ["string"], "hostname": "string", "session_id": "string", "timestamp": "ISO" } ``

1. Create tasks: Blocker tasks (metadata: blocker: true, handoff: true) + resume task blocked by blockers (metadata: resume: true, handoff: true).
2. Output:

`` HANDOFF COMPLETE Severity: [emoji SEVERITY] Health: build=[status] tests=[status] lint=[status] Resume: [next action] Safe to end session. ``

Severity

| Level | Condition | |-------|-----------| | CRITICAL | Build failing, prod down, security issue | | IN_PROGRESS | Tests failing, uncommitted work, mid-feature | | READY | All green, clean state |

Anti-Patterns

DON'T: Skip health checks. Write vague resume ("keep working on X"). Leave READY with failing tests. DO: Exact error messages. Specific file:line in resume. Honest severity.

Gotchas

• Atomic write (mv .tmp.$$ state.json) fails silently if .handoff/ doesn't exist yet. Always bootstrap the directory before writing.
• jq is an allowed tool but not guaranteed installed. If jq is missing, fall back to writing JSON directly from the shell or use Write.
• Health checks can hang indefinitely on projects with interactive test watchers (Jest --watch, Vitest default). Always pass --watchAll=false or --run flags.
• Setting severity to READY when there are uncommitted changes is a lie. Uncommitted work means IN_PROGRESS, even if build/test/lint all pass.
• The session_id field is only useful for --resume on the same machine. If the user switches devices, the resume hint is misleading.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ramonclaudio
• Source: ramonclaudio/skills
• License: MIT

Install and usage instructions live in the source repository linked above.