Skip to content

sno-ai/sno-station-skills / skills/S-communication-and-handoff/handoff/skill

handoff

Verified

Transfer full task ownership to a fresh agent with a verified brief and explicit release. Use for replacing the current executor, including a directly assigned task with no work card; not for supervising a helper.

FileKindSize
SKILL.mdskill md18.8 KB
references/reach-contract.jsonconfig1.4 KB
scripts/handoff-checkpointexecutablescript10.1 KB
scripts/handoff-checkpoint.texecutablescript12.0 KB
scripts/selftest/run-selftest.shscript167 B
scripts/selftest/text-check.pyscript12.7 KB

scripts/handoff-checkpoint

View on GitHub
#!/usr/bin/env bash
# Usage: sno handoff-checkpoint [--repo DIR] [FILE] | --verify FILE.
# Keeps a progress record that a fresh agent can resume from when the working agent is gone.
#   sno handoff-checkpoint FILE create FILE, or refresh its machine record. The record holds what
#                               git and the file system can state: checkout, branch, head, recent
#                               commits, and every uncommitted path with its SHA-256. Text outside
#                               the record markers (Done, Next, decisions...) is the agent's and is
#                               never touched. The checkout is the git work tree of the current
#                               directory, or of --repo.
#   sno handoff-checkpoint --verify FILE
#                               compare the record with the checkout it names. Exit 0 and MATCH when
#                               nothing moved; exit 1 and one DRIFT line per difference otherwise.
#                               MATCH covers the branch, HEAD and the working-tree content of every uncommitted
#                               file; it does not compare what is staged.
# Exit 2: unusable input (with one line saying why). Needs bash 4+; without GNU coreutils (macOS) also python3.
# Keep FILE outside the checkout when you can; inside it, FILE itself is not counted as work.
set -Eeuo pipefail

if (( BASH_VERSINFO[0] < 4 )); then
    printf 'handoff-checkpoint needs bash 4+; found bash %s\n' "$BASH_VERSION" >&2
    exit 2
fi

# GNU tools first; BSD stat and python3 where GNU is absent (macOS).
file_mode() { stat -c %a -- "$1" 2>/dev/null || stat -f %Mp%Lp -- "$1"; }
resolve_path() {  # like realpath -m: resolve the parts that exist, require nothing to exist
    realpath -m -- "$1" 2>/dev/null ||
        python3 -c 'import os, sys; sys.stdout.buffer.write(os.path.realpath(os.fsencode(sys.argv[1])))' "$1"
}

readonly START='<!-- machine-record:start -->'
readonly END='<!-- machine-record:end -->'

usage() {
    local status="${1:-2}"
    printf 'usage: sno handoff-checkpoint [--repo DIR] [FILE] | --verify FILE\n' >&"$((status == 0 ? 1 : 2))"
    exit "$status"
}
die() { printf 'handoff-checkpoint: %s\n' "$1" >&2; exit 2; }

# git_state <top> <path-to-ignore>: sets BRANCH HEAD_SHA HEAD_LINE RECENT and UNCOMMITTED (path -> "XY hash").
declare -A UNCOMMITTED=()
BRANCH='' HEAD_SHA='' HEAD_LINE='' RECENT=''
git_state() {
    local top="$1" skip="$2" entry xy path hash
    BRANCH="$(git -C "$top" symbolic-ref --short -q HEAD || printf '(detached)')"
    if HEAD_LINE="$(git -C "$top" -c core.abbrev=12 log -1 --format='%h %s' 2>/dev/null)"; then
        HEAD_SHA="${HEAD_LINE%% *}"
        RECENT="$(git -C "$top" -c core.abbrev=12 log -5 --format='%h %s')"
    else
        HEAD_LINE='none'; HEAD_SHA='none'; RECENT=''
    fi
    UNCOMMITTED=()
    while IFS= read -r -d '' entry; do
        xy="${entry:0:2}"; path="${entry:3}"
        [[ "$path" == "$skip" || ( -n "$skip" && "$path" == "$skip.lock" ) ]] && continue
        if [[ -f "$top/$path" ]]; then hash="$(sha256sum <"$top/$path" | cut -d' ' -f1)"; else hash='-'; fi
        UNCOMMITTED["$path"]="${xy// /} $hash"
    done < <(git -C "$top" status --porcelain=v1 -z --untracked-files=all --no-renames)
}

# rel_to_top <top> <file>: the file's path relative to the checkout when it lives inside it, else nothing.
rel_to_top() {
    local abs
    abs="$(resolve_path "$2")"
    if [[ "$abs" == "$1"/* ]]; then printf '%s' "${abs#"$1"/}"; fi
}

has_markers() { grep -qxF "$START" -- "$1" && grep -qxF "$END" -- "$1"; }
record_field() { sed -n "/^$START\$/,/^$END\$/{s/^$2: //p;}" "$1" | head -n1; }

write_record() {  # <top> <checkpoint-number>
    local path rest
    printf '%s\n' "$START"
    printf 'checkpoint: %s\nupdated: %s\nby: %s\ncheckout: %s\nbranch: %s\nhead: %s\nrecent:\n' \
        "$2" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "${SNO_REACH_ADDR:-unknown}" "$1" "$BRANCH" "$HEAD_LINE"
    if [[ -n "$RECENT" ]]; then printf -- '- %s\n' "${RECENT//$'\n'/$'\n- '}"; fi
    printf 'uncommitted:\n'
    for path in "${!UNCOMMITTED[@]}"; do
        printf '%s\t%s\n' "$path" "${UNCOMMITTED[$path]}"
    done | LC_ALL=C sort | while IFS=$'\t' read -r path rest; do
        printf -- '- %s %s sha256:%s\n' "${rest%% *}" "$path" "${rest#* }"
    done
    printf 'runtime: %s\nsession-id: %s\n' "$RUNTIME" "$SESSION_ID"
    printf '%s\n' "$END"
}

TMP='' BLOCK='' RUNTIME='' SESSION_ID=''
cmd_write() {  # <file> <repo>
    local file="$1" repo="$2" top n=0 lock_fd
    [[ -d "$(dirname -- "$file")" ]] || die "the folder for the record does not exist: $(dirname -- "$file")"
    if command -v flock >/dev/null 2>&1; then
        exec {lock_fd}>"$file.lock"
        flock -x "$lock_fd"
    fi
    if top="$(git -C "$repo" rev-parse --show-toplevel 2>/dev/null)"; then
        git_state "$top" "$(rel_to_top "$top" "$file")"
    else
        [[ -d "$repo" ]] || die "not a directory: $repo"
        top="$(resolve_path "$repo")"
        BRANCH=none; HEAD_LINE=none
    fi
    if [[ -e "$file" ]] && has_markers "$file"; then
        n="$(record_field "$file" checkpoint)"; n="${n:-0}"
        RUNTIME="$(record_field "$file" runtime)"
        SESSION_ID="$(record_field "$file" session-id)"
    fi
    if [[ -n "${CODEX_THREAD_ID:-}" ]]; then
        RUNTIME=codex; SESSION_ID="$CODEX_THREAD_ID"
    elif [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
        RUNTIME=claude-code; SESSION_ID="$CLAUDE_SESSION_ID"
    fi
    n=$((n + 1))
    TMP="$(mktemp "${file}.XXXXXX")"; BLOCK="$(mktemp "${file}.XXXXXX")"
    trap 'rm -f -- "$TMP" "$BLOCK"' EXIT
    write_record "$top" "$n" >"$BLOCK"
    if [[ -e "$file" ]] && has_markers "$file"; then
        chmod "$(file_mode "$file")" "$TMP"
        awk -v blockfile="$BLOCK" -v start="$START" -v end="$END" '
            $0 == start { while ((getline line < blockfile) > 0) print line; skipping = 1; next }
            $0 == end { skipping = 0; next }
            !skipping { print }
        ' "$file" >"$TMP"
    elif [[ -e "$file" ]]; then
        chmod "$(file_mode "$file")" "$TMP"
        { cat -- "$BLOCK"; printf '\n'; cat -- "$file"; } >"$TMP"
    else
        chmod 644 "$TMP"
        {
            # shellcheck disable=SC2016  # the backticks are literal text in the record
            printf '# Progress record\n\nStart the task you were given first: do not read or edit this record before your first action on it. Update it only when there is real progress to record (a finished step, a decision, a failure, an orderly stop or compaction), and only with your file edit tool, never through a shell command. Keep Next and its expected result accurate and record the latest failed operation, target and error. The block below is rewritten by the command; everything else is yours.\n\n'
            cat -- "$BLOCK"
            printf '\n## Objective and authorization\n\n## Done\n\n## Next\n\n## Decisions and assumptions\n\n## Known failure\n\n## Report destination\n\n## Reach card\n\n## Risks and open questions\n'
        } >"$TMP"
    fi
    mv -- "$TMP" "$file"
    printf 'checkpoint %s written to %s\n' "$n" "$file"
}

cmd_verify() {  # <file>
    local file="$1" top old_branch old_head line path hash count files='' head_lines=''
    [[ -f "$file" ]] || die "no such progress record: $file"
    has_markers "$file" || die "not a progress record (no machine-record markers): $file"
    top="$(record_field "$file" checkout)"
    old_branch="$(record_field "$file" branch)"
    old_head="$(record_field "$file" head)"; old_head="${old_head%% *}"
    [[ -n "$top" && -d "$top" ]] || die "the recorded checkout does not exist here: ${top:-none}"
    if [[ "$old_branch" == none && "$old_head" == none ]]; then
        printf 'No git state to compare.\n'
        return 0
    fi
    git -C "$top" rev-parse --show-toplevel >/dev/null 2>&1 || die "the recorded checkout is not a git work tree: $top"

    declare -A was=()
    while IFS= read -r line; do
        if [[ "$line" =~ ^-\ ([^\ ]+)\ (.*)\ sha256:([0-9a-f]{64}|-)$ ]]; then
            was["${BASH_REMATCH[2]}"]="${BASH_REMATCH[3]}"
        fi
    done < <(sed -n "/^$START\$/,/^$END\$/p" "$file" | sed -n '/^uncommitted:$/,$p' | sed '1d;$d')

    git_state "$top" "$(rel_to_top "$top" "$file")"
    printf 'checkpoint %s of %s, by %s\n' "$(record_field "$file" checkpoint)" "$(record_field "$file" updated)" "$(record_field "$file" by)"

    if [[ "$HEAD_SHA" != "$old_head" ]]; then
        if count="$(git -C "$top" rev-list --count "$old_head..$HEAD_SHA" 2>/dev/null)"; then
            head_lines+="DRIFT head moved $old_head..$HEAD_SHA ($count commit$([[ "$count" == 1 ]] || printf s) since)"$'\n'
        else
            head_lines+="DRIFT head is now $HEAD_SHA and the recorded $old_head is not in its history"$'\n'
        fi
    fi
    [[ "$BRANCH" == "$old_branch" ]] || head_lines+="DRIFT branch $old_branch -> $BRANCH"$'\n'
    for path in "${!UNCOMMITTED[@]}"; do
        hash="${UNCOMMITTED[$path]#* }"
        if [[ -z "${was[$path]+x}" ]]; then files+="DRIFT new: $path"$'\n'
        elif [[ "${was[$path]}" != "$hash" ]]; then files+="DRIFT changed: $path"$'\n'
        fi
    done
    for path in "${!was[@]}"; do
        [[ -n "${UNCOMMITTED[$path]+x}" ]] && continue
        if [[ -e "$top/$path" ]]; then files+="DRIFT settled: $path (no longer uncommitted)"$'\n'; else files+="DRIFT gone: $path"$'\n'; fi
    done
    if [[ -z "$head_lines$files" ]]; then printf 'MATCH\n'; return 0; fi
    printf '%s' "$head_lines"
    [[ -z "$files" ]] || printf '%s' "$files" | LC_ALL=C sort
    return 1
}

argc=$# mode=write repo='' file=''
while (( $# )); do
    case "$1" in
        -h|--help) usage 0 ;;
        --verify) mode=verify ;;
        --repo) (( $# >= 2 )) || usage; repo="$2"; shift ;;
        -*) usage ;;
        *) [[ -z "$file" ]] || usage; file="$1" ;;
    esac
    shift
done
if [[ -z "$file" ]]; then
    if [[ "$mode" == write && -n "${CODEX_THREAD_ID:-${CLAUDE_SESSION_ID:-}}" ]]; then
        file="${SNO_PROFILE_DIR:-$HOME/.sno}/station/handoff/${CODEX_THREAD_ID:-$CLAUDE_SESSION_ID}.md"
        mkdir -p -- "$(dirname -- "$file")"
    elif (( argc == 0 )); then usage 0
    else usage
    fi
fi
case "$mode" in
    write) cmd_write "$file" "${repo:-.}" ;;
    verify) cmd_verify "$file" ;;
esac
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall