{
  "name": "handover",
  "description": "Generate a dated session-handover note in the workspace docs/handover dir, mirroring the established note structure (header, commits, checks, resume path, resume trigger). Writes the file directly into the gitignored private tree — never stages, never commits, never touches tracked files.",
  "intent": {
    "guarantee": "This skill writes only into the gitignored private workspace tree, and only ever proposes — the operator commits",
    "forbidden": [
      "git add",
      "git commit",
      "git push",
      "git tag",
      "touch any tracked file"
    ]
  },
  "capabilities": [
    { "kind": "tool", "name": "Read" },
    { "kind": "tool", "name": "Write" },
    { "kind": "tool", "name": "Grep" },
    { "kind": "tool", "name": "Glob" },
    { "kind": "tool", "name": "Agent" },
    { "kind": "tool", "name": "Task" },
    { "kind": "tool", "name": "AskUserQuestion" },
    { "kind": "bash", "verb": "git status", "scope": "*" },
    { "kind": "bash", "verb": "git log", "scope": "*" },
    { "kind": "bash", "verb": "git diff", "scope": "*" },
    { "kind": "bash", "verb": "git describe", "scope": "*" },
    { "kind": "bash", "verb": "git branch --show-current", "scope": "*" },
    { "kind": "bash", "verb": "git stash list", "scope": "*" },
    { "kind": "bash", "verb": "date", "scope": "*" },
    { "kind": "bash", "verb": "ls", "scope": "*" },
    { "kind": "bash", "verb": "find", "scope": "*" },
    { "kind": "bash", "verb": "head", "scope": "*" }
  ],
  "steps": [
    {
      "index": 0,
      "title": "Gather session facts",
      "body": "Collect the facts the handover note records. Run the read-only commands below, then from the conversation note: what was worked on this session, which commits landed (match against the log), which checks or gates ran and their results, what is unfinished, and any explicit operator decisions made during the session. If the session's work is not visible in git (uncommitted tree, or work that lives only in the private tree), say so in the note — the next session's divergence check depends on an accurate working-tree state.",
      "runs": [
        "git status --short",
        "git log --oneline -15",
        "git describe --tags --always",
        "git branch --show-current",
        "git stash list",
        "date +%F"
      ]
    },
    {
      "index": 1,
      "title": "Determine the filename",
      "body": "Name the note handover_<YYYY-MM-DD>[_<slug>].md under the workspace handover dir. Take the date from `date +%F`, never from memory. Derive the slug from the session's main outcome (stage + landmark); confirm with the operator if it is ambiguous. If a note with today's date already exists, ask whether to write a second slugged note or extend the existing one."
    },
    {
      "index": 2,
      "title": "Mirror the established structure",
      "body": "Read the newest existing handover note as the format template and mirror its section structure rather than imposing a fixed skeleton — the format is allowed to drift with use. The stable core is: a title with the date and a status headline; a header block (date, branch @ SHA, working-tree state, goal); a 'this session' section listing each commit (SHA, subject, one-line note) or, when nothing was committed, the working-tree / private-tree state; a working-tree-state section for the next session's divergence check; a checks/gates section naming what ran with results and what did NOT run; a numbered resume path with concrete commands; a 'what not to redo' section; standing constraints and memory references; and a resume trigger.",
      "runs": [
        "ls -t <handover-dir>/handover_*.md",
        "head -120 <newest-handover>"
      ]
    },
    {
      "index": 3,
      "title": "Write the note content",
      "body": "Draft the note against the structure from Step 2. Keep every claim concrete — SHAs, exact counts, exact file paths, exact commands — so the next session can act without re-deriving anything. Technical terms, commit subjects, and command lines stay verbatim. Internal jargon and private-tree paths are expected here; this is the private tree, the inverse of a leak-swept public commit message."
    },
    {
      "index": 4,
      "title": "Write the file and tidy the dir",
      "body": "Write the note with the Write tool to the Step 1 path. If older handover notes in the dir would now shadow the newest one in the resume search, ask the operator whether to move them into an archive subdir — move with `mv`, never delete, and only on explicit confirmation. Print the path written, the status headline, and a one-line reminder that the note is in the gitignored private tree (nothing to commit). Never stage, never commit, never touch a tracked file."
    }
  ],
  "output_format": "Print three lines: the path written, the one-line status headline, and a reminder that the note is gitignored (nothing to commit).",
  "maps_to_workflow": "handover-refresh"
}