AGENT SKILL

pactile-handoff

Condense the current session into a portable handoff document so a new agent / harness / directory can continue the work. User-invoked when the work needs to 'travel' (switch harness, switch directory or repo, hand to a colleague, or fork a side branch); writes to the OS temp directory and reports the full path.

License 许可
AGPL-3.0
所属仓库
blxzer77/pactile
最近更新
2026-10-01
Stars
★ 16
Forks
0

01 前言 Front Matter

name
pactile-handoff
description
Condense the current session into a portable handoff document so a new agent / harness / directory can continue the work. User-invoked when the work needs to 'travel' (switch harness, switch directory or repo, hand to a colleague, or fork a side branch); writes to the OS temp directory and reports the full path.
argument-hint
What will the next session use this for?
disable-model-invocation
true

03 SKILL.md 正文

pactile-handoff — Session handoff

Condense the current session into a portable handoff document (pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md), written to the OS temp directory (does not pollute the workspace), so a new agent can continue without the original session. User-invoked (disable-model-invocation: true — the agent never triggers it on its own; it is written only when the user invokes /pactile-handoff).


How this differs from a task handoff.md (read first)

The two have opposite purposes — not interchangeable:

This skill (session handoff) Task handoff.md
What Portable cross-session summary Child-task integration / implementation-window delivery evidence
Where OS temp directory (volatile) .pactile/tasks/<task>/ (durable, archived with the task)
Lifecycle Single transfer; dead once the work lands Kept with the task evidence for Parent / review traces

A task directory's handoff.md is the evidence file for integrate-child / review-child, not a session handoff document; the temp file this skill produces is not task evidence.

When to use / when not (five-question tree)

At stage boundaries first ask: does the work still continue in this session?

  1. Continue — default preference: keep going in this session
  2. Clear — context can be dropped; clear and restart
  3. Handoff — the work needs to travel → this skill
  4. Subagent — a side branch can run in parallel while the main session stays → dispatch a subagent (optionally with a handoff file)
  5. Compact — same harness, same directory, only intent compression needed → use the platform compact

Handoff only when the work needs to travel, triggered by exactly four situations:

Situation Why a file is needed
Switch tasks or hosts The destination may not see the previous context
Switch directory / repo Common for prototype directories and new repos
Hand to a colleague They need something they can read independently
Fork a side branch (main line continues) You stay in this session; a second agent takes a copy in parallel

Same harness, same directory continuation → compact / continue, not handoff. The value of handoff is portability, not better compression; if only intent compression is wanted, /compact is the better fit.

Steps

  1. Read the user argument: the "next-session purpose" passed on invocation decides which whys to keep (trim key decision rationale by purpose — do not take everything verbatim).
  2. Write the temp file (path rules below).
  3. Report the full absolute path (required): temp paths are long and differ per OS; the user must get the path first.
  4. Remind about volatility: the temp file may be cleaned by the environment (Codex clears temp across sessions; /private/tmp is lost on reboot). For cross-hour / cross-harness continuation, ask the user to copy it to a durable location immediately (this also applies to other temp files referenced by the document).

Path rules (Windows first)

$env:TEMP\pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md
  • Windows: $env:TEMP (i.e. %TEMP%), e.g. C:\Users\<user>\AppData\Local\Temp\pactile-handoff-20260808-153000-migrate-ts.md
  • Linux / macOS: $TMPDIR/pactile-handoff-{yyyyMMdd-HHmmss}-{slug}.md (/tmp when $TMPDIR is unset)
  • After writing, always report the full absolute path to the user (Write-Host or plain text) — never just the filename.

Content template (English skeleton)

Follow artifact_locale when the project uses it; English by default.

# Session handoff — <work summary>

> Generated by pactile-handoff at <time> · Next-session purpose: <user argument>

## Goal
<what the in-flight work is trying to achieve>

## Done
- <items>

## Not done / Blocked
- <items>

## Next steps
1. <ordered steps>

## Key whys (trimmed by next-session purpose)
- <decision + reason; whys unrelated to this purpose can be omitted>

## Facts vs unverified beliefs
- Facts: <verified>
- Beliefs (unverified): <assumptions — never write them as facts>

## Pointers (reference paths only, never copy bodies)
- Task: `.pactile/tasks/<task>/` (prd.md / design.md / implement.md / verify.md)
- Context: `CONTEXT.md` · Research: `<task>/research/`
- Prototype evidence (if a prototype was involved): `<task>/research/prototype-<slug>.mjs` (see `.pactile/spec/guides/prototype-guide.md` §9)
- Other: ADR / issue / commit / diff paths or URLs

## Suggested skills (for the continuing agent)
- <skill name list, e.g. pactile-brainstorm, pactile-check, pactile-continue>

Rules

  • Reference, don't copy: anything already on disk (spec / PRD / ADR / issue / commit / diff) gets a path or URL only, never pasted verbatim. The document should be a small part of the session; a path list replaces copying.
  • Redact: API keys, tokens, passwords, PII → replace with <REDACTED> before writing; when unsure, write <REDACTED>.
  • Facts vs beliefs: unverified assumptions must be marked, never written as verified facts — the continuing agent will treat the document as a contract and will not re-check.
  • Prototype evidence pointer: when the session involved a prototype, list the prototype evidence path in the pointers section (prototype-guide.md §9: git throwaway branch or a task research/ path snapshot) and confirm the evidence is captured before cleanup.
  • Delivery: have the new agent read the file path; do not stuff the summary into shell quotes to launch the new agent (backticks / $(...) get swallowed and silently truncated).

Anti-patterns

  • ❌ Treating handoff as a long-lived document: it is a transit document for a single transfer and dies once the work lands (long-term facts belong in AGENTS.md / spec, not handoff)
  • ❌ Pasting large spec / PRD / diff bodies (should reference paths only)
  • ❌ Stuffing the summary into shell quotes to launch the next agent (silent truncation risk)
  • ❌ Not reporting the full path / not reminding about temp volatility
  • ❌ Writing a handoff for same-harness same-directory continuation (should compact / continue)
  • ❌ Writing keys / tokens into the document

04 同仓库更多 Skills