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

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

   plan:
     - repo-a/openspec/changes/slug-0004-short-name/
     - repo-a/openspec/changes/slug-0009-short-name/