_handoffs/ folder, synced via Git between Mac and VPS — no more silos._kickoffs/ sibling folder so launch prompts are easy to find.~/.claude/rules/handoffs.md (currently missing — we create it).Right now your handoffs are scattered across 10 different folders on two machines, with five different naming conventions, and no sync between them. Stuff that has nothing to do with n8n is living in the n8n folder.
Everything moves into one folder at the top of your code home, prefixed with an underscore so it sorts above project folders. Same structure on Mac and VPS, kept in sync via Git.
Most handoffs are just one file. But some need transcripts, screenshots, context dumps, or sample data alongside them. Rule: everything for one handoff lives together so when it moves through its lifecycle, the context moves with it.
When a handoff moves between states, its kickoff file (see next section) moves with it.
You mentioned having a hard time organizing kickoff prompts. Here's the fix:
Source of truth: the fenced code block at the bottom of every handoff.md (unchanged).
Generated sibling: a tiny file at _handoffs/_kickoffs/<name>.md containing just the launch prompt and a link back to the handoff.
When you need to launch a chat, you browse _kickoffs/ — flat list, just prompts, easy to scan. The handoff-creator skill writes both files automatically going forward.
Both Mac and VPS check the same private GitHub repo. The _handoffs/ folder lives in that repo. Markdown is small, syncs cheap, and you get a full edit history for free.
Edge case: if a handoff genuinely contains a secret (rare — most reference IDs, not tokens), it goes in _handoffs/_local/ instead. That subfolder is gitignored so it stays on the machine where you wrote it.
Migration 02 will move them in three batches. You don't have to do anything — the migration handoff handles it.
| What | How | Where it lands |
|---|---|---|
~113 files in handoffs/done/ | Big-bang move | _handoffs/done/ |
Files in handoffs/parked/ | Big-bang move | _handoffs/parked/ |
Files in handoffs/active/ | Lazy — moves when next touched | _handoffs/active/ |
session-report-*.md, team-*.md dumps | Big-bang to archive | _handoffs/_archive/ |
handoffs/team-runs/ | Big-bang move | _handoffs/active/team-runs/ |
_dev0/handoffs/ho-*.md | Stay put | (migration-specific, untouched) |
| VPS — 9 silos | Merge into one | /home/dev/_handoffs/active/ |
Safety net: active handoffs leave a 30-day symlink at the old path so any in-flight chat that says "Read handoffs/handoff-X.md" still works.
The current root cause of drift is that no master rules file exists — every project copy of handoffs.md defines its own conventions, and bot sessions write wherever the project tells them to.
~/.claude/rules/handoffs.md | Master. Created fresh. Auto-loaded every session. |
<project>/.claude/rules/handoffs.md | Trimmed down to project-specific overrides only. |
Skill files (handoff-creator, closeout, dev0-report, team-builder) | Path strings updated from handoffs/ → _handoffs/active/. Migration 02 has the line-level list ready. |
handoff-<short-kebab-case-description>.mdOptional project prefix when the topic is ambiguous: handoff-kdp-keyword-strategy.md, handoff-tts-vendor-sweep.md, handoff-dispatch-bot-routing.md. That's it.
The numbered ho-N.M-… pattern stays inside _dev0/migration/ for migration-step handoffs only — it doesn't leak into _handoffs/.
~/code/, ~/projects/, etc.) is decided by Migration 01, not 01.1. Paths above use <TOP_LEVEL> as a placeholder.baton-pass, consolidate, handoff-review) don't exist on disk. Migration 02 will need to add them to the skill update list if they show up._dev0/migration/architecture-decisions.md.