Write Agent Handoff

Write Agent Handoff

Create one concise, resumption-ready snapshot from the current task state, save it, report the continuation essentials, and stop. Do not turn the handoff into new task execution.

Routing

Not for ordinary status reports, implementation plans, or PR descriptions. The feature planner's canonical blind implementation handoff is its own artifact and is never produced here.

Required resources

1. Read REFERENCE.md completely before inspecting task state. It defines evidence, freshness, redaction, Git and non-Git capture, and conflict handling.
2. Render the artifact from templates/agent-handoff.md. Preserve its nine section headings and their order exactly once; replace every prompt.
3. Consult EXAMPLES.md for the closest matching coding, debugging, non-code, or nested-directory case.

Workflow

1. Freeze the invocation location and target

• Record the absolute invocation working directory before any inspection, repository discovery, or directory change. Keep that value fixed for the whole invocation. Never search for or substitute a repository root when choosing the output base; a Git root discovered later is context only.
• Record a capture-start UTC timestamp now. Record the distinct capture-complete UTC timestamp after the last pre-save observation; use the latter for Captured at, the freshness boundary, and the default filename.
• Default to <invocation-directory>/handoffs/<task-slug>-handoff-<capture-complete-UTC>.md, where the timestamp is YYYYMMDDTHHMMSSZ and the slug is short kebab-case. REFERENCE.md holds slug construction and how a user-supplied override resolves.
• Default the recipient to next agent when the user does not name one.

2. Establish a safe inspection boundary

• Classify likely sensitivity from source identity, filenames, and metadata before reading content. Treat logs, environment/configuration files, authentication material, crash dumps, transcripts, and unknown user artifacts as potentially sensitive.
• Keep secrets out of the capture channel, not just the finished Markdown: filter source-side before any output is emitted. Never print raw content and redact afterward.
• If safe filtering is unavailable or uncertain, do not read the content. Record an unknown with its impact and a path to a sanitized export instead.
• Choose the narrowest defensible sensitivity level and keep inspection and references appropriate to it. REFERENCE.md lists what may never appear, the redaction markers, and the access controls each level requires.

3. Capture the pre-save state

• Use conversation context, user-supplied artifacts, and only targeted read-only live checks needed for safe continuation.
• For Git work, discover repository root, branch or detached state, HEAD, concise status, staged and unstaged summaries, and only the diff details relevant to resumption.
• For a graph feature workflow, read only the exact supplied workflow state. Record its revision, physical common-Git identity, frozen target, package/worktree/checkpoint map, terminal-review record, and every pushed branch/PR state. Query each recorded PR by exact number or head before calling mutable GitHub state observed; never scan for a newest state or infer missing stack members.
• Capture workspace state before creating the output directory or file so the handoff does not invalidate its own snapshot. Preserve all existing files and state.
• Timestamp mutable workspace, external-system, process/job, and verification claims.
• Mark material claims as [observed], [reported], or [inferred]. Preserve contradictions instead of selecting a convenient version.
• Record inaccessible or uncertain information as an unknown with its impact and a concrete resolution path. Do not block creation merely because a source is unavailable.

4. Compose the continuation contract

• Use exactly one status from: in-progress, blocked, awaiting-input, awaiting-external, ready-for-review, or ready-for-verification.
• State one immediate next safe action, not a menu of alternatives.
• Describe commits and staged, unstaged, and untracked changes separately when present, including their intent without claiming ownership that the evidence does not support.
• Populate the Feature delivery stack table from the exact state revision. Preserve total stack order, stable WP* identities, physical worktree paths, original and restacked commit IDs, explicit PR bases, draft/ready state, and pending operations. Use one N/A row for work that is not a graph feature workflow.
• Record verification as passed, failed, not run, or not applicable; never imply success from an absent result.
• Start resume steps with state revalidation. Give every step dependencies, prerequisites, and an observable done condition.
• Give every blocker, risk, and unknown an owner and unblock condition, or a concrete resolution path when an owner is unknown.
• State whether the output and referenced artifacts are durable or temporary. Treat any temporary path or expiring store as a risk with a safe preservation/regeneration path.
• Omit checksums unless they are supplied evidence or materially disambiguate artifacts. When one is necessary, preserve the exact observed value without manual retyping and verify it before publication.

5. Save immutably

• Never overwrite or edit an existing handoff. Treat an existing regular handoff as a collision: append -v2, then -v3, and so on before .md, rechecking each candidate.
• If a same-task snapshot already exists in the target directory, link the newest prior snapshot from the new handoff's References section. Never modify the prior snapshot.
• Reject a target, target directory, or newly traversed output component that is a symlink or unexpected special file. That is an unsafe-path blocker, not an ordinary collision; never follow it or relocate silently.
• Publish the complete artifact with an exclusive, no-follow, no-clobber operation and verify the published content before returning. If a concurrent writer wins, retry the next version suffix; never use a check-then-overwrite sequence. REFERENCE.md holds the publication and access-control procedure, including when inability to enforce controls is itself a write blocker.
• When <invocation-directory>/handoffs/ is inside a Git worktree and is not ignored, record that risk in the handoff and warn the user after saving. Do not edit the target repository's ignore rules.
• Run the template self-check in REFERENCE.md, then write exactly one new artifact.
• If output creation fails, report the resolved target and blocker without modifying an older handoff or any task state.

6. Return and stop

Return:

1. the saved path;
2. critical blockers, risks, or evidence gaps, or none; and
3. the single immediate next action.

That return is the only post-write response. After writing, do not continue implementation, run new tests, commit, push, update issues or tickets, post or send external messages, or start, stop, or manage jobs.