Skip to content

vunm-io/passdown / plugins/passdown/skills/passdown-handoff

passdown-handoff

Verified

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:

## 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/
    

    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.
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: 468kUpdated Claude CodeCodexVerifiedInstall
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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 321kUpdated Claude CodeCodexVerifiedInstall