handover

name	handover
description	Use when the user says "new epic", "new task", "new standalone", "end session", "update status", "handover", "handover-resume

Handover System

Tracks epics, tasks, and standalones across sessions. Multi-repo capable: state lives per registered repo under <repo-root>/handovers/<user>/, optionally bucketed by source repo under <repo-root>/handovers/<user>/<bucket>/ (HIMMEL-129 layout — see references/resolution.md).

This SKILL.md is a thin router (HIMMEL-1041). It carries only the op index + invariant rules. Each op's mechanics live in references/<op>.md, loaded on demand — so invoking one op never loads the other ~19. The read path (handover-resume) is fully script-driven and skips the skill entirely (HIMMEL-1038).

Before any mutation op — load the shared substrate

All mutation ops resolve the target repo the same way and share the registry protocol, template placeholders, the No-ID picker, status values, and the file-path map — that shared substrate lives in references/resolution.md; load it first, then the op's own slice below. Most (new-epic, new-task, new-standalone, end-session, update-status, bucket, priority, jira-link, hygiene, consolidate) also resolve bucket and run inside the worktree gate before writing; next-ID derivation applies only to the new-* creation ops. defaults is the exception — it resolves only the target repo and writes ~/.claude/handover/registry.json (no bucket, ID, or worktree). Read-only ops (handover-resume, repos list) skip the worktree gate.

Commands (load the slice on demand)

Create / update items

• new-epic <name> · new-task <epic-id> <name> · new-standalone <name> — create a tracked item (Jira auto-create gate + worktree + templates). → references/new-item.md
• update-status — regenerate status.md + roadmap.md + tech-debt.md from filesystem state; run after any mutation, never ask. → references/update-status.md
• end-session [id] — write the next append-only next-session-N.md (session summary + cold-start prompt + Jira transition); carries the overnight-mode trigger. → references/end-session.md

Move / link / configure items

• /handover bucket <id> <bucket> (time-horizon OR source-repo move) · /handover priority <id> <priority> · /handover jira-link <id> [<key>] · /handover defaults <sub> → references/item-ops.md

Bugs & lessons (script-backed)

• /handover bug <add|fix|status> · /handover bugs [--open] · /handover lessons → references/bug-ops.md

Maintenance

• /handover hygiene [triage|consolidate|analyse] · /handover consolidate apply <N> → references/hygiene.md

Resume (read-only, script-driven — no skill load)

• handover-resume #N — the /handover-resume command calls scripts/handover/resume.sh directly and does NOT load this skill (HIMMEL-1038). If reached via skill trigger: → references/resume.md

Setup & registry

• /handover-setup — first-time bootstrap (Mode A inline / Mode B external state repo). Full runbook: the plugin's commands/handover-setup.md.
• /handover init — bootstrap a NEW target repo (no existing state). → references/init-register.md
• /handover register — adopt EXISTING state, idempotent. → references/init-register.md
• /handover repos <list|add|remove|where> — manage the repo registry (read-only reads; list skips the worktree gate). → references/init-register.md

Critical Rules

• Resolve target repo before any read or write. Never assume a single repo.
• Resolve target bucket (HIMMEL-129) before any read or write when the bucket layer is active under <state-root>. Bucket layer = any recognized source bucket exists directly under <state-root> — the four built-ins himmel/, luna/, luna_brain/, cross/ plus any names in the host repo's source_buckets_extra (HIMMEL-307). See references/resolution.md.
• Scan for ID: Never trust counter.md alone — always reconcile against filesystem max.
• Worktree always: All file writes to the target repo's <state-root> happen in a worktree of the target repo — never on main. The machine-global registry (~/.claude/handover/registry.json, written only by defaults/repos) is not a target-repo write, so it needs no worktree (see the op index above).
• context.md ≤1 page.
• Templates are canonical: Never modify <state-root>/_templates/ files via mutation commands. Copy and fill.
• status.md auto-generated. Always regenerate via update-status.
• Slugs: lowercase, hyphens, ≤30 chars. # prefix is part of dir name.
• Session files append-only.

Capturing Human Feedback

When user gives feedback on work during chat, capture it to the relevant reviewer-notes.md under ## Human Feedback. Proactively — don't wait to be asked. Resolves under the target repo of the work being reviewed.

Capturing Bug Fixes

When a fix is attempted during debugging and fails, append it to the active item's bug before moving on — proactively, don't wait to be asked: /handover bug fix <BUG-n> FAILED "<what you tried + why it failed>" (or bug add "<symptom>" first if the bug isn't tracked yet). When a fix works, record WORKED and set status resolved. This Fixes tried FAILED/WORKED ledger is the circular-debugging breaker — it stops a later session (or a post-compaction you) from re-trying a fix that already failed. Resolves under the target repo of the work being debugged (same resolver as Human Feedback).

References (load on demand)

• references/resolution.md — shared substrate: repo/bucket/registry resolution, ID derivation, worktree gate, template placeholders, No-ID picker, status values, supplementary files, file-path map
• references/new-item.md — new-epic / new-task / new-standalone
• references/update-status.md — update-status + roadmap.md / tech-debt.md generation
• references/end-session.md — end-session + cold-start format + overnight mode
• references/item-ops.md — bucket / priority / jira-link / defaults
• references/bug-ops.md — bug / bugs / lessons
• references/resume.md — handover-resume (script-driven via scripts/handover/resume.sh)
• references/routing.md — full resolution algorithm, canonicalisation, edge cases
• references/init-register.md — full specs for init, register, repos; registry schema + defaults keys
• references/buckets.md — WIP context-detection rule + bucket vocab
• references/hygiene.md — stale tiers, lingering detection, triage/consolidate/analyse + hygiene/consolidate op flow
• references/sync.md — bidirectional Jira sync
• references/v2-schema.md — v2 frontmatter schema