Passdown Handoff

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: 
- 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:

/YYYY-MM-DD__-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.

1. Write these sections (in the configured language):

• Header: date, agent, status (DONE / IN_PROGRESS / BLOCKED),

branch, related plan/change (link if any).

• 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 traps live nowhere else.

1. Sync task state: if executing against a plan, update its checkboxes

to match reality (for OpenSpec work: tasks.md of the change). Task state belongs in the plan; the log tells the story around it.

1. Route leftovers: unimplemented ideas/decisions go to the workspace's

backlog or inbox per its conventions — not into the session log.

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vunm-io
• Source: vunm-io/passdown
• License: MIT

Install and usage instructions live in the source repository linked above.