spectre-handoff

handoff

Purpose

Persist the smallest complete state needed to resume the current branch. Finish in 2–3 tool calls and emit only the final confirmation.

Inputs

• $ARGUMENTS: task name; default to the raw current branch.
• Current conversation/session memory: goal, completed and active work, decisions, constraints, blockers, risks, open questions, next steps, active files/IDs, recent verification commands, outer workflow routing, and any nonempty agent-native todo list.
• Late-bound repository state: raw branch, HEAD, worktree status, canonical/legacy handoff history, and optional healthy bd tasks labeled with the branch.

Working Set

• CANONICAL_DIR=.spectre/handoffs/{raw-branch}; slash-containing branches intentionally create nested directories.
• LEGACY_DIR=docs/tasks/{raw-branch}/session_logs is read-only fallback history.
• Canonical *_handoff.json history wins. Use matching legacy history only when canonical history is empty; count that selected history so the first canonical handoff continues its numbering.
• New handoffs and todo snapshots write only under CANONICAL_DIR. Resolve timestamp, selected history directory, and output path once and pass them literally; never reconstruct branch identity from paths.

Outputs + DONE

Write {timestamp}_handoff.json as valid JSON with this exact v1.1 shape:

{
  "version": "1.1",
  "timestamp": "YYYY-MM-DD-HHMMSS",
  "branch_name": "raw branch",
  "task_name": "argument or raw branch",
  "session_number": 1,
  "progress_update": {
    "summary": "string",
    "goal": "string",
    "accomplished": [],
    "now": "string",
    "next_steps": [],
    "confidence": "high|medium|low",
    "constraints": [],
    "decisions": [],
    "blockers": [],
    "open_questions": [],
    "risks": []
  },
  "working_set": {
    "key_files": [],
    "active_ids": [],
    "recent_commands": []
  },
  "beads": {
    "available": true,
    "workspace_label": "raw branch",
    "task_count": 1,
    "epic_id": null,
    "epic_title": null,
    "tasks": [{"id":"", "title":"", "status":"", "type":"", "parent":null, "children":[], "labels":[]}]
  },
  "context": {
    "wip_state": "uncommitted|clean",
    "last_commit": "short SHA"
  }
}