handoff-skill

Handoff is an agent skill aimed at repositories where the same work is picked up across several AI-agent sessions. Its problem statement: a task left unchecked in a list is not necessarily unfinished, because another agent may have implemented it, a commit may have satisfied it, the requirement may have changed, or someone else may still own the affected files. The skill uses a shared ledger file, HANDOFF.md, together with repository evidence such as Git history, current code, tests and ownership, to decide what is actually outstanding. The recorded workflow has six stages. Preflight claims a session name and returns, from one versioned snapshot, every open ledger entry with its steps, a summary of recent finished entries, structure errors and Git state. Intake turns each request into a dated task entry with separate In progress and Completed checkboxes, steps, verification and a status line. A progressive audit weighs later ledger entries, commits, current source, live ownership and the older entry's checkboxes, then classifies the effective scope as Complete, Partially complete, Superseded, Unfinished or Unknown, annotating rather than deleting so history is preserved. Ownership resolution asks whether eligible work should be finished first or left with its current owner before a new task starts, unless the user has already given an explicit ordering. Safe writes route updates through a locked compare-and-swap when peers may write the same tree. Finally the agent stages explicit paths, records verification and commit identifiers, and leaves a state the next agent can continue from. Ledger entries record an owner label, an optional harness field (auto-detected for Claude Code, Codex, Cursor and VS Code, overridable via an environment variable), state boxes, checked and unchecked steps, a status line and a next action. Completed tasks keep both boxes checked so the ledger reads as history. Sessions claim names from a roster of a hundred mythological figures, handed out on a first-come basis and never duplicating an owner already present in the ledger. The project ships a standard-library Python CLI with a live curses dashboard for agents and tasks, showing completed versus total tasks, in-progress and pending counts, step progress and, where recorded, the harness each owner used. It can also run in a plain-text snapshot mode, a read-only mode, or behind a PATH launcher that resolves the current version-pinned install. The dashboard supports cutting a task and pasting it onto another owner, which rewrites the owner label and records the move under the same lock. A status-bar script prints a one-line progress row and is documented as working with Claude Code, Grok CLI and Kimi Code status lines, with a tmux wrapper for Codex and other CLIs. A local agent channel stores messages and acknowledgements in a gitignored SQLite file scoped to one checkout, with no daemon or socket. Agents can send questions, reply, report availability, release their unfinished bucket, declare a renewal deadline on a lease, and use challenge/attest nonce exchanges to show another agent is responsive. Installation is offered as a Claude Code plugin from a marketplace, a Cursor marketplace import, or via npx skills add for other hosts; the README states that Git, an agent with repository read/edit access, and Python 3.9+ are required, with no API key, hosted service or third-party Python package. The only feature that leaves the machine is an opt-in ssh publish step that stays inactive until a configuration file exists. Five slash commands cover initialising, viewing, status, continuing and purging the ledger, and the README notes Windows limits for the curses dashboard and the status-bar fast path.