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?
- Continue — default preference: keep going in this session
- Clear — context can be dropped; clear and restart
- Handoff — the work needs to travel → this skill
- Subagent — a side branch can run in parallel while the main session stays → dispatch a subagent (optionally with a handoff file)
- 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
- 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).
- Write the temp file (path rules below).
- Report the full absolute path (required): temp paths are long and differ per OS; the user must get the path first.
- Remind about volatility: the temp file may be cleaned by the environment (Codex clears temp across sessions;
/private/tmpis 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(/tmpwhen$TMPDIRis 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_localewhen 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 taskresearch/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
external-review
User-installed review workflow that Pactile may borrow but never delete.
team-skill
Existing team workflow with no Pactile ownership record.
verify-basic
Verify observable behavior at pre-agreed public seams.
observability-local
Record sanitized local execution and decision evidence.
intake-basic
Scope new work before creating an independently acceptable Task.
execute-agent
Implement the approved change inside the frozen write set.