Handoff Archive

Handoff Archive

Move stale handoff docs into per-project archive/ subdirs and update INDEX statuses. The operation is reversible (it's just a mv).

Args

/handoff-archive [--older-than=30d] [--status=done|resumed|open|all] [--project=current|all] [--dry-run]

Defaults: --older-than=30d, --status=done,resumed, --project=current, --dry-run=false. Multiple statuses comma-separated.

The defaults match the most common housekeeping case: tidy up handoffs that have already been picked up or completed and are over a month old. To archive open (un-resumed) handoffs, pass --status=open explicitly.

Steps

1. Resolve candidates

Read the INDEX ($HANDOFF_INDEX_PATH or ~/.claude/handoffs/INDEX.md) or scan the FS as fallback. Rely on column ORDER (Date | Project | Slug | Status | Path), never on header text — headers may be localized in a pre-existing INDEX. Apply all three filters: --older-than (against the first/date column), --status, --project. Status matching compares ONLY the first token of the status cell — annotations like resumed @ 2026-06-16 09:16 or done @ ... (verified) must never break parsing.

--older-than formats: Nd (days), Nw (weeks), Nm (months, treated as 30d). Default 30d.

2. Plan moves

For each candidate doc at /.handoffs/.md:

• Target: /.handoffs/archive/.md. Create archive/ if missing.
• INDEX status transition: current → archived.

3. Dry-run path

If --dry-run is passed, output planned moves as a table; do not touch the filesystem:

Would archive (dry-run, no changes made):

  /.handoffs/2026-04-12-1130-foo.md → archive/  (resumed, 42 days old)
  /.handoffs/2026-04-15-1500-bar.md → archive/  (resumed, 39 days old)

2 candidates. Re-run without --dry-run to apply.

4. Execute moves (non-dry-run)

For each candidate:

1. mv via the Bash tool (real mv, not Write+Delete — preserves mtime).
2. Update the INDEX row: status cell → archived @ YYYY-MM-DD HH:MM (timestamp via date '+%Y-%m-%d %H:%M'), preserving prior status info as an annotation, e.g. archived @ 2026-06-07 17:31 (done 2026-06-07). Also update the link in the path cell to the new archive/ location.

If mv fails for one file, continue with the rest, collect errors, report all at the end.

5. Report

Archived:  handoff(s).
  ✅ 2026-04-12-1130-foo.md → archive/
  ✅ 2026-04-15-1500-bar.md → archive/
  ❌ 2026-04-20-0900-baz.md  (mv failed: )

INDEX updated:  rows.

Undo: mv /.handoffs/archive/.md /.handoffs/ and edit INDEX manually.

Edge cases

• --older-than=0d: allowed (archives even just-created docs). Useful for cleaning up an accidental write.
• Cross-project archive (--project=all): never silent — list affected projects first, ask y/n. Always.
• Source file missing (already moved manually): skip with note, don't error.
• Target file exists in archive/ (rare collision): append -archive-N suffix to the filename, log in the report.
• No matches: "No candidates for the current filters. Try --status=all or --older-than=0d."

Restoration

Not a separate sub-skill (rare operation). Documented in the report output: the user runs mv manually and edits the INDEX. Building a dedicated restore skill would be over-engineering for the frequency.

Universal rules (apply to this skill)

• Paths absolute in output.
• Timestamps local time, YYYY-MM-DD HH:MM — obtain via date '+%Y-%m-%d %H:%M', never estimate.
• Output language follows user's conversation language.

Source & license

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

• Author: aploe
• Source: aploe/claude-handoff-skill
• License: MIT

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