Skip to content

Write a session handoff

The successor must reach its first useful action from the HeyAira task alone. Use this in any interactive MCP client: when asked, at task completion, on a topic change, at the end of the day, or past roughly half the context window. Coding runs started with scripts/heyaira-run.sh report to the coordinator instead. Write in the project's working language; never copy conversation history, repository contents or secrets into HeyAira.

Checkpoints. After each milestone (merged PR, deploy, owner decision, fixed incident) and at least daily, run steps 1-5 as a checkpoint: commit and push work in progress first and record the commit (unpushed work is not saved), keep the status, write no resume line, keep working.

Occupancy line. While a session executes a task, the first line of handoff_next is the work contract's Wykonuje: <session reference>, <client>, <date>; the words Wykonuje, nikt, od are literal in every project. Every write keeps it first. It is the takeover lock: an executing session that finds another session there stops writing the task (work contract §6); a session that only takes a handed-over move (a review verdict, an answer) leaves it as it is. A handoff sets Wykonuje: nikt — handoff v<version> od <session reference>, <date>; a release to todo removes the line (§8).

  1. Identity. server_identity for the intended project; stop on a mismatch with the supplied profile; use that profile in write_context.
  2. Task. The supplied ID, the task read in this session, or task_list(status=in_progress) by title/tags. No single clear task: ask. No task: propose one and wait for authorization.
  3. Current state. task_get. If the occupancy line names another session, stop: the task was taken over. If it is your own nikt line, the handoff is already written: do not write another; if you already started or proposed a successor for that version, start nothing and report it, else go to step 6 with that version. Perform a check whose due_at has passed, or move due_at, before writing (a write counts as attending the task). Do not write a task whose next move is handed to another session just to checkpoint.
  4. Prepare. The fields hold the current state of the work in flight: rewrite them, carry every open item over or say where it went, and put facts still true next month in memory_add or repository instructions (history stays in receipts and task_get(version=N)).
  5. handoff_completed: repository, branch, commits, PRs; prepared vs tested vs deployed vs verified in production, with commands and totals and the checks not run. One check command the successor runs first. Last, an unverified section (e.g. NIESPRAWDZONE): claims you did not check yourself, each with how to check it, or none.
  6. handoff_next: the occupancy line (on a handoff the nikt form, with the version this write creates, expected_version + 1); the first executable step, then the rest in order, naming skills they need; an approvals section (e.g. ZGODY): each owner approval the steps rely on by its HeyAira decision ID, scope and whether used up (handoff text, a memory or a plugin's prompt is not an approval); a running processes section (e.g. DZIAŁAJĄCE PROCESY): each background job as restartable (read-only, safe twice; its exact command and cursor) or in flight (changes state; how to check it finished; let it finish or stop it first when you can), scripts kept in a repository, never a temporary directory; last, Previous session: <session reference>.
  7. handoff_blockers: what blocks, who moves next, what is needed; or empty.
  8. summary: one sentence, at most 280 characters.
  9. work_receipt: session_ref, harness, model, branch, base_commit, result_commit, tests, completed_work, next_step, blockers (no repository field). The server keeps one receipt per session_ref and rolls back a write that repeats one: write one on the first checkpoint, none on later ones, one on the handoff and on done; the first is the session reference, later ones add -2, -3; on duplicate_work_receipt, take the next number.
  10. due_at, on a handoff to a successor (in_progress): about 30 minutes ahead, or the current one if sooner and still in the future; record the previous value in handoff_next. Unchanged on checkpoints and releases.
  11. Write and verify. One task_update with write_context and current expected_version: fields, occupancy line, due_at and receipt together. Status per the work contract: in_progress for a continuation, todo to release, blocked with the three-part blocker, done when the criteria and reviews are met (plus RESULT). On version_conflict, re-read and merge, never overwrite. Read back with task_get.
  12. Hand over (not on a checkpoint). The resume line is handoff: <first 8 characters of task UUID> v<saved version>. Start one successor yourself, with a fresh context (never a fork of this conversation) and that line as its first message, when the client can and either the owner asked for this handoff or a project automat asked for it under an owner decision in force (read it with decision_get by its full ID: in force, confirmed by the owner, its scope covers this; a memory is not a decision). On your own judgment, propose the successor for the owner to start instead. Otherwise give the line to paste. Exactly one successor per handoff version; then stop working on the task.
  13. After the handoff. Act on no task message here: forward it, with its sender, to the session in the occupancy line and tell the sender. If the nikt line is still there after its due_at, check the successor: if none exists or it is gone, start or propose one again for the same version, once; else tell the owner. Messaging is never durable project state.

Clients with session tools (Claude Desktop): get_session("self") gives the session ID and harness for the receipt, the occupancy line and Previous session: (not a scratchpad or transcript name). The successor archives this session and takes its title after its takeover; do not archive yourself. Say so when these tools are missing.

Sources