handoff

boshu2/agentops

Write compact session handoff artifacts with exact evidence paths for context handoff without choosing continuation.

What is handoff?

The handoff skill documents completed work, unresolved items, and exact artifact paths so the next context can act on verifiable facts rather than narrative memory. Use it when transitioning between sessions or contexts to record goal, completed evidence, remaining work, and risks.

Records caller-supplied goal and session summary with exact evidence paths (e.g., `cli/internal/gates/regen.go`)
Documents completed artifacts, unresolved acceptance criteria, findings, and causal uncertainties
Captures measured remaining allowance, repository identity, and session/context IDs
Writes to caller-authorized handoff location (`.agents/ao/handoff/` or external CDLC path)
Preserves work-to-session associations with frozen source bounds and digests
Prevents optimistic closure by requiring verifiable artifact paths, not phantom claims

How to install handoff

npx skills add https://github.com/boshu2/agentops --skill handoff

Prerequisites

Caller must supply goal, summary, and authorized handoff location
Session must have observable completed artifacts with exact paths
Caller optionally provides continuation text and work association metadata

Claude Code

Cursor

Windsurf

Cline

How to use handoff

1.Trigger the skill with 'handoff' or 'write compact session handoff'
2.Supply the session goal, completed artifacts with exact file paths, and unresolved items
3.Specify the authorized handoff location (e.g., `.agents/ao/handoff/` or external CDLC path)
4.Optionally include continuation text, repository identity, and session/context IDs
5.The skill writes the artifact to the specified location and returns the path

Use cases

Good for

Handing off a partially completed migration task with exact file paths and remaining documentation work
Recording session state when switching between coding agents or contexts mid-project
Documenting unresolved risks and acceptance gaps so the next context knows what still needs verification
Transitioning work between team members or sessions with reproducible evidence instead of chronological narration
Capturing native repository identity and runtime facts for interrupted sessions that need resumption

Who it's for

Coding agents managing multi-session projects
Teams coordinating work across context switches
Developers needing to resume interrupted tasks with verifiable state
Projects requiring audit trails of what was completed versus what remains

handoff FAQ

What should I include in a handoff?

Include caller-supplied goal and summary, completed artifacts with exact evidence paths (not chronological narration), unresolved acceptance criteria and risks, measured remaining allowance, repository identity, session IDs, and optional caller-supplied continuation text.

What is 'optimistic closure' and how do I avoid it?

Optimistic closure is writing 'done' for work whose evidence path does not exist. Avoid it by only recording artifacts that can be verified at exact paths; if a path doesn't exist, record it as unresolved or a gap.

Can the handoff skill choose the next action or assign work?

No. The skill only writes factual session state. It does not infer next actions, select work, assign ownership, change tracker state, or restart runtime—the caller decides continuation.

Where does the handoff artifact get written?

To the caller-authorized location: typically `.agents/ao/handoff/` for Git-based handoffs, or an external CDLC path for protected memory/episode evidence. The caller specifies the destination.

What if I don't know a session ID or repository identity?

Record it as explicit unknown rather than inventing it. The handoff contract requires you to preserve unknowns and missing observations with their provenance instead of assuming monotonically correct knowledge.

Full instructions (SKILL.md)

Source of truth, from boshu2/agentops.

name: handoff description: 'Write compact caller-authored session evidence without choosing continuation. Triggers: "handoff", "write compact session handoff".' practices: [adr, wiki-knowledge-surface, code-complete] hexagonal_role: supporting consumes: [] produces: [caller-selected handoff artifact] context_rel: [] skill_api_version: 1 context: window: inherit intent: {mode: none} metadata: capabilities: [handoff] effects: [write_handoff_artifact, read_git_state, read_clock] canonical_status: canonical disposition: keep_specialist graph_root: true tier: session dependencies: [] output_contract: caller-authored handoff artifact

Handoff

A handoff works because the next context can act on exact paths and facts without trusting the author's memory; any line the reader cannot verify from the artifact itself is decoration, not handoff.

Prompt

Write a handoff for this session in agentops-wt/train2-c: goal was
migrating regen to Go, I finished cli/internal/gates/regen.go and left
scripts/regen-all.sh untouched, tests are green, and the next context
still needs to update docs/CI-CD.md. Write it to .agents/ao/handoff/.

It's working if

Observable in the trace, without reading the prose:

Every completed item names an exact evidence path like cli/internal/gates/regen.go, not a chronological narration.
The artifact lands at the caller-named authorized path; new CDLC evidence uses an explicitly selected external non-Git location.
Readback of that exact artifact path shows the content written.
Only caller-supplied continuation text appears as next action; no owner, tracker state, or verdict is invented.

Contract

Write a factual session artifact that another context can read. Include:

caller-supplied goal and summary;
completed artifacts and exact evidence paths;
unresolved acceptance, findings, causal uncertainties, and risks;
for a bounded goal, observed native stop/continuation state, measured remaining allowance or explicit measurement gaps, and whether the one helper for the current HOLD incident was already used, with existing evidence references;
optional caller-supplied continuation text;
best-effort read-only repository identity when useful;
the permitted startup association reference, source-store/project/work identity, and observed runtime/session/context IDs or explicit unknowns;
separately evidenced parent and resume links, observation provenance and cutoff, and any supported work spans with available frozen source bounds and digests, following session associations.

The caller records the work association at dispatch/start and observed native identity at startup through native comments/metadata or runtime facts. Handoff adds end-state evidence; it must not be the first or only work/session link. For an interrupted session, reconstruct only what permitted startup records and native observations support. Missing handoff, missing source, unknown length, unobserved ID or unproved relationship remains explicit; never invent an ID or assign an entire multi-work session to one bead. Preserve earlier unknown/failure observations when later evidence resolves a link.

Check source-owner and recipient/model/destination authorization before reading or copying association metadata. BD/Dolt is versioned and is not a secret store. Use permitted opaque locators where necessary; omit restricted excerpts and sensitive paths from unauthorized destinations. A locator grants no access.

Do not infer a next action, select work, assign ownership, consume the artifact, change tracker or Git state, classify a verdict, govern retries, or restart a runtime. Reading a handoff must not mutate it. A report saying HOLD or NEEDS_OPERATOR is not evidence that a native goal paused; record the actual observed state and operator action still required. Compaction or handoff never resets an allowance, repair bound, or helper incident. Retain informative red and withdrawn claims with their provenance instead of presenting knowledge as monotonically correct.

Named failure mode — optimistic closure: writing "done" for work whose evidence path does not exist, so the next context builds on a phantom.

Anti-pattern: narrating the session chronologically ("first I tried…, then…"). Corrective: record end-state facts — artifacts, paths, unresolved risks — and drop the journey.

Write the artifact to the caller-owned authorized handoff location. For new CDLC memory/episode evidence, require the caller-selected protected external non-Git location; missing routing is a reported gap, with no fallback file in the consumer checkout. Existing requested evidence stays preserved. Standalone non-CDLC handoff retains the explicit requested-proof default below. There is no permanent generic handoff store — an artifact nobody consumes is scratch.

The skill may write Markdown when that better serves a human. The existing ao session handoff and ao session rehydrate JSON compatibility behavior below does not itself establish startup associations or an external CDLC route; use only a command whose actual destination support matches the invocation.

Earlier default compatibility

JSON artifacts already stored under .agents/handoff/ remain read-only evidence. ao session handoff writes new JSON to .agents/ao/handoff/, while ao session rehydrate searches both directories and selects the newest lexical handoff id; if an identical filename exists in both, the canonical .agents/ao/handoff/ copy wins. No command moves or deletes the legacy files. Human-authored Markdown consumers receive the exact path, so they do not need to scan either default. This owning skill contract is the compatibility authority; no separate migration artifact is required.

Return the artifact path and stop.