vunm-io/passdown / plugins/passdown/skills/passdown-handoff
passdown-handoff
VerifiedUse when ending or pausing a work session — writes a session handoff log (the "passdown") so the next session or agent resumes cheaply from small files instead of replaying a large transcript
Passdown Handoff
End every working session with a passdown: a small file the next shift reads to catch up. State lives in files, never in the session.
Configuration (read first)
Build the effective passdown configuration root-to-nearest. Read applicable
AGENTS.md files from the workspace/repository root down to the current
directory, plus any parent file explicitly referenced by a thin entrypoint.
Merge ## passdown keys in that order: nearer values override the same key and
inherit omitted keys. Resolve relative paths against the file that declared
them.
The effective configuration should contain:
## passdown
- log_dir: <path for session logs>
- log_language: en # or another language for human-facing logs
If a required key is still missing, ask where session logs should live and
suggest adding it to the appropriate AGENTS.md.
Process
-
Create ONE new log file:
<log_dir>/YYYY-MM-DD_<short-topic>_<agent>-HHMMSS.md. Before writing, check whether the path already exists. On collision, add an incrementing suffix (-2,-3, ...) and create a new file; never truncate or append to another session's or agent's file. -
Start with machine-readable frontmatter, then the body sections (in the configured language). The frontmatter is what lets the next shift — or
passdown-pickup— filter logs without reading them in full:--- status: DONE # DONE | IN_PROGRESS | BLOCKED branch: <git branch> agent: <agent identity — the host name (claude|codex|kiro) unless the workspace names agents> plan: <path to the plan/change this session executed, or none> ---plan:paths must resolve from the workspace root — no repo shorthand, arrows, or prose, becausepassdown-pickupopens them mechanically. A session that executed several plans lists them all:plan: - repo-a/openspec/changes/slug-0004-short-name/ - repo-a/openspec/changes/slug-0009-short-name/The
agentvalue must match the<agent>field in the filename. Body sections:- Summary: 2–5 sentences — what was worked on and the outcome.
- What was done: concrete items with numbers; commit SHAs and key file paths (clickable).
- Next steps: checkboxes the next session can start on immediately.
- Caveats / traps: known pitfalls discovered this session. This is the highest-value section — task state lives in the plan, but a fresh trap lives nowhere else yet (step 4 promotes the durable ones).
-
Sync task state: if executing against a plan, update its checkboxes to match reality (for OpenSpec work:
tasks.mdof the change). Reality means accepted work, not claimed work:- a task this session did itself (
main) is[x]once its verification passed; - a delegated task is
[x]only when its latestDispatched:line is an accepted verdict aspassdown-dispatchdefines it:acceptedwith a check the host ran. Lines written before theacceptedwording existed count as accepted when they report success and name a host check afterverified:— keep those[x]. Never tick a delegated task because the worker reported success, because its files exist, or because the worker ticked the box itself; - delegated work that is still unverified goes back to (or stays)
[ ], and the log's Caveats / traps names it as unverified so the next shift verifies it before building on it.
Task state belongs in the plan; the log tells the story around it. Any done/total counts quoted in the log are then counted from the synced plan file — never recalled from the session; a drifted count sends the next shift to the wrong task.
- a task this session did itself (
-
Route leftovers: unimplemented ideas/decisions go to the workspace's backlog or inbox per its conventions — not into the session log. The same goes for traps with project lifetime (a toolkit default, a platform quirk — anything that still bites ten sessions from now): promote those into the repo's durable docs (
AGENTS.mdor the doc that owns the topic) and keep the log's copy as the session record. Only session-scoped traps live in the log alone. -
Do not commit unless the user asks or the workspace's conventions say sessions end with a commit.
Rules
- The log complements, never duplicates, the plan: plan = which tasks are done; log = why we stopped here and what to avoid.
- Keep it short enough that the next session actually reads all of it.
- Write only your own log file; check
git statusbefore touching shared files (AGENTS.md, templates) to avoid overwriting another agent's work.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |