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
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
SKILL.md
View on GitHub---
name: passdown-handoff
description: Use 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:
```markdown
## 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
1. **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.
2. **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:
```markdown
---
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, because `passdown-pickup` opens them mechanically. A
session that executed several plans lists them all:
```yaml
plan:
- repo-a/openspec/changes/slug-0004-short-name/
- repo-a/openspec/changes/slug-0009-short-name/
```
The `agent` value 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).
3. **Sync task state**: if executing against a plan, update its checkboxes
to match reality (for OpenSpec work: `tasks.md` of 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 latest `Dispatched:` line is
an accepted verdict as `passdown-dispatch` defines it: `accepted`
with a check the host ran. Lines written before the `accepted` wording
existed count as accepted when they report success and name a host
check after `verified:` — 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.
4. **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.md` or 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.
5. **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 status` before 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: 472k | 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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |