# Handoff > | - **Type:** Skill - **Install:** `agentstack add skill-broomva-skills-handoff` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [broomva](https://agentstack.voostack.com/s/broomva) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [broomva](https://github.com/broomva) - **Source:** https://github.com/broomva/skills/tree/main/skills/orchestration/handoff - **Website:** https://skills.sh/broomva/skills ## Install ```sh agentstack add skill-broomva-skills-handoff ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # handoff — Fresh-session handoff doc skill **Compress a substantive arc into a single resumable doc the next agent loads cold.** ## Why this skill exists Across the 7-day window 2026-05-18 → 2026-05-24, **nine fresh-session handoff docs** were drafted by hand. Six landed in `docs/handoffs/` (Houston substrate completion, BRO-1208 streaming hang, Houston advanced-settings wave, Life-Houston H1 runner refactor, Stage 1 fresh-session, etc.) and three landed in `docs/conversations/HANDOFF-*` (substrate completion arc, BRO-1180 four pillars, Spec J real-Anthropic smoke). All shared the same shape — the recurrence met rule-of-three (P16) ~3× over. Before this skill, the writer rebuilt the structure each time: which sections appear, what order, what level of detail per section, which git SHAs to cite, how to phrase the "first action". The skill captures the canonical shape so subsequent handoffs are produced consistently in a single pass. ## What this skill provides 1. **Template** (`references/handoff-template.md`) — the canonical section structure, with annotations explaining each section's purpose and stop condition. 2. **Anti-patterns** below — what NOT to include (the failure modes that produce unusable handoffs). 3. **Composition rules** — when to use this skill alone vs. compose with `persist` (P12), `bookkeeping`, or `make-spec`. ## When to invoke - **End of substantive in-session work** that another agent (or the same user in a fresh context) will resume. - **Mid-arc snapshot** when context is approaching 100K tokens and the user wants to break before continuing in a fresh context (this is the *handoff* half of P12 — `PROMPT.md` is the *state-replay* half). - **Stage boundary** in a multi-stage arc (Stage 0 → Stage 1 → Stage 2 pattern that appeared 4× in the Houston/Life-Houston work). - **Before merging the last PR of a substantial arc** so the next agent inherits the arc's lessons and remaining loose ends. ## Carve-outs (do not invoke) - Single-PR work that's fully self-contained → just the PR description suffices. - Pure read questions → no handoff needed. - Continuation of work in the same context → no fresh-context boundary. - Personal-life retrospective → use the Telos surface, not this. ## The canonical shape (mirrors `references/handoff-template.md`) ``` --- arc: # stable queue slug (== broomva handoff push --as) specs: [] # related spec handles → /d/ ticket: BRO-NNNN priority: 0 # queue_id / queue_slug / queue_version / queue_status / queue_url / pushed_at # are written back by `broomva handoff push` — do not hand-edit. --- # — **TL;DR.** ## State of the world (P15 snapshot YYYY-MM-DD) - **** — , ahead N / behind M vs origin/main. Last commits … - **** — , last merged PRs with SHAs. - **** — STILL RUNNING / DEAD; restart command if dead. ## What delivered (so the next agent doesn't redo it) | PR | Crate(s) / files | What it gave | |----|------------------|--------------| | #N | … | … | ## E2E proof (re-runnable any time the prereqs hold) ```bash # Expected: ``` ## First action ## Pickup state (what's open) - [ ] - [ ] ## Related context - Lessons doc: `docs/.md` - Linear: BRO-NNNN - Prior handoff: `docs/handoffs/.md` ``` ## The five anti-patterns this skill exists to prevent | Anti-pattern | Failure mode | Fix | |---|---|---| | **Missing P15 snapshot** | Fresh agent reasons against stale state (last-seen instead of current); duplicates work or conflicts with unmerged work. | Always include git status + branch + ahead/behind + open PRs + daemon state. | | **No "first action" / vague "first action"** | Fresh agent spends 10+ minutes triangulating where to start. | Pick ONE concrete next step with the exact command/file path. If ambiguous, pick anyway and document the alternative as "if blocked, try X". | | **PR table without SHAs** | Fresh agent can't reproduce the substrate state; doesn't know whether a PR landed or just opened. | Always cite the merge SHA next to each delivered PR. | | **Lessons buried in prose** | Lessons silently lost because no skim-reader will find them in paragraph 8. | Pull lessons into a labeled section OR link to a separate `-lessons.md`. | | **Aspirational scope** | "Next we should also do A, B, C, D, E …" with no priority. Fresh agent thrashes. | List ONLY the next 1–3 actions. Defer A, B, C, D, E to Linear backlog or a separate planning doc. | ## File placement - **Workspace handoff** (cross-repo or workspace-governance): `docs/handoffs/YYYY-MM-DD-.md` - **Project-local handoff** (single repo): `/docs/handoffs/YYYY-MM-DD-.md` - **Legacy location** (still acceptable, gradually migrate): `docs/conversations/HANDOFF-YYYY-MM-DD-.md` Filename slug should name the **arc**, not the date. The date is the mtime, the slug is the identifier. ## Push to the Maestro queue (BRO-1415) A handoff on local disk is invisible to the next session until someone opens the file. **After writing the `.md`, push it to the Maestro handoff queue** so it surfaces at [`broomva.tech/maestro/queue`](https://broomva.tech/maestro/queue) — the realtime, owner-gated queue that articulates *what to hand off next*, relates each handoff to its HTML specs, and exposes the copy-to-continue trigger (the same Copy/Continue a fresh session uses on the spec board, BRO-1399). ```bash broomva handoff push docs/handoffs/2026-06-05-.md \ --as \ --spec \ # repeatable — the /d/ specs this relates to --ticket BRO-NNNN # → Queue: https://broomva.tech/maestro/queue ``` The CLI auto-extracts the **title** (first `# ` heading), **TL;DR** (the `**TL;DR.**` lead line), and **first action** (the `## First action` section → the Copy-button payload), and records git provenance (repo / branch / commit / path). Re-pushing the same `--as ` appends a version and supersedes the prior queued entry, so iterating a handoff is safe. This is a **reflex, not a request** (P6 · Bookkeeping): push the handoff, then report the queue URL — don't ask permission first. | Field | Source | Used for | |---|---|---| | `title` | first `# ` heading | queue card headline | | `tldr` | `**TL;DR.**` line | queue card subtitle | | `firstAction` | `## First action` section | the **Copy** button payload | | `specRefs` | `--spec ` (repeatable) **or** frontmatter `specs` | related-spec chips → `/d/` | ### Frontmatter is the control surface (BRO-1418) The handoff `.md` carries a YAML frontmatter block that is **both the publish input and the queue reference** (see `references/handoff-template.md`). You set `arc` / `specs` / `ticket` / `priority`; `broomva handoff push` reads them (CLI flags override) and **writes the queue identity back** into the same block: ```yaml --- arc: maestro-handoff-queue specs: [maestro, maestro-relay-phase-1b] ticket: BRO-1415 priority: 0 # --- written back by `broomva handoff push` — do not hand-edit --- queue_id: a1b2c3d4e5f6 queue_slug: maestro-handoff-queue queue_version: 2 queue_status: in_progress queue_url: https://broomva.tech/maestro/queue pushed_at: 2026-06-06T01:55:00Z --- ``` So the file **references its own queue entry**. Re-pushing the same arc appends a version and updates the frontmatter in place — iterating a handoff is safe and traceable. The body sent to the server is the narrative with the frontmatter stripped. (`--no-write-back` opts out.) ### Managing the lifecycle from the file The lifecycle verbs accept `` — pass the handoff file and the CLI resolves `queue_id` from its frontmatter and mirrors the new status back, so the file stays the source of truth: ```bash broomva handoff pick-up docs/handoffs/.md # queued → in_progress broomva handoff done docs/handoffs/.md # → done (mirrors queue_status) broomva handoff archive docs/handoffs/.md # set aside, off the active queue broomva handoff requeue docs/handoffs/.md # back to waiting broomva handoff rm docs/handoffs/.md # delete + clear the queue_* block broomva handoff list # the active queue ``` **When you finish an arc, mark its handoff `done`** — it keeps the queue honest (the analytics throughput + pickup-latency metrics depend on it). This too is a reflex, not a request. > **Prereq:** frontmatter publish + lifecycle ship in the `broomva` CLI > ≥ the BRO-1418 release (the queue itself is BRO-1415). If `broomva > handoff` is unknown or lacks the lifecycle verbs, rebuild > (`cargo install --path crates/broomva-cli` in `broomva.tech`) or fall > back to opening the queue and pasting — but the canonical path is the > CLI push. ## Composition rules | Compose with | When | |---|---| | **`persist` (P12)** | When the handoff is the prelude to a fresh-context loop. The handoff is the human-readable narrative; `PROMPT.md` is the machine-readable state. Both exist; they're different artifacts. | | **`bookkeeping`** | When the handoff cites lessons that should also live as entity pages (`research/entities/pattern/.md`). File the lesson via `bookkeeping file` AFTER the handoff is written; reference the entity in the handoff's "Related context" section. | | **`make-spec`** | When the handoff is dense enough that a separate HTML companion (spec / plan) is warranted. The handoff stays markdown; the companion is HTML. P18 audience rule: handoff is agent-loaded → markdown. | | **`/p9 watch`** | If the handoff is being written mid-CI (after a push, before merge), include the watch command + PR number so the next agent doesn't restart the wait. | ## Validation (handoff self-test) A well-formed handoff passes all five checks: - [ ] **TL;DR** is one sentence and names the first action explicitly - [ ] **P15 snapshot** covers every repo touched in the arc + every long-running daemon - [ ] **PR table** cites merge SHAs (not just PR numbers) - [ ] **First action** is a single concrete step with the exact command or file path - [ ] **Pickup state** lists ≤5 open threads (more than 5 = aspirational scope; split into a separate plan doc) - [ ] **Pushed to the queue** via `broomva handoff push … --spec ` so the next session sees it at `/maestro/queue` (reflex, not a request) ## References - Canonical examples: `docs/handoffs/2026-05-24-stage1-fresh-session.md`, `docs/handoffs/2026-05-23-life-houston-h1-runner-refactor.md`, `docs/handoffs/2026-05-22-bro-1208-streaming-hang-handoff.md` - Template: `references/handoff-template.md` - Related primitive: P12 persist (cross-context loop); P15 state-snapshot; P18 audience - Related skills: `persist`, `bookkeeping`, `make-spec`, `autonomous` ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [broomva](https://github.com/broomva) - **Source:** [broomva/skills](https://github.com/broomva/skills) - **License:** MIT - **Homepage:** https://skills.sh/broomva/skills Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-broomva-skills-handoff - Seller: https://agentstack.voostack.com/s/broomva - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.