handoff

361stars51forks

How to install handoff?

dsifry/metaswarm/handoff

$npx -y skills add dsifry/metaswarm --skill handoff

Installs into the current project.

Summary

Analyze the current session and write a self-contained handoff document so a fresh agent can resume the work with full context — outputs a single "Read XXX.md and do YYY." sentence

Files · 1

SKILL.md

1	# Handoff Skill
2
3	Capture everything a fresh agent with zero prior context needs to resume the current work, write it to a single self-contained markdown document, and hand it off with one unambiguous sentence:
4
5	> Read `docs/handoffs/<file>.md` and do `<the next concrete action>`.
6
7	Use this when a session is ending, when context is about to be compacted, when you are switching machines or sessions, or when the user explicitly asks for a handoff. The goal is zero context loss: the receiving agent should be able to act correctly after reading exactly one file.
8
9	---
10
11	## Output Contract
12
13	This skill produces exactly two things:
14
15	1. A handoff document at `docs/handoffs/handoff-<YYYY-MM-DD-HHmm>.md` (created if the directory does not exist). It is comprehensive, self-contained, and links to — or quotes — every artifact the next agent must read.
16	2. A single closing sentence, and nothing else after the document is written, of the exact form:
17
18	```text
19	Read docs/handoffs/handoff-2026-06-17-1432.md and do <YYY>.
20	```
21
22	Where `<YYY>` is one concrete, actionable next step (an imperative, not a vague theme). Good: "implement the `parseConfig` validation in `src/config.ts:84` and make `tests/config.test.ts` pass". Bad: "continue the work" / "look into the config stuff".
23
24	The sentence is the deliverable the user hands to the next agent. The document is what makes that sentence safe to follow.
25
26	---
27
28	## Method
29
30	### Step 1 — Reconstruct what we are working on
31
32	Review the session to date and answer, concretely:
33
34	- Objective: What is the user actually trying to accomplish? State it in one or two sentences.
35	- Definition of Done: What does "finished" look like? Enumerate verifiable acceptance criteria if any exist.
36	- Why: The motivation/problem behind the task, so the next agent does not re-litigate settled decisions.
37
38	Pull from: the user's original request, any GitHub Issue (`gh issue view <n>`), the design/plan docs, and the arc of the conversation.
39
40	### Step 2 — Load any persisted metaswarm state
41
42	If this project uses metaswarm's context persistence, read and fold in whatever exists — do not duplicate it blindly, summarize and link:
43
44	```bash
45	ls .beads/plans/active-plan.md # the approved plan (if mid-execution)
46	ls .beads/context/project-context.md # completed work units, patterns, tooling
47	ls .beads/context/execution-state.md # current work unit, phase, retry count
48	bd prime --work-type recovery 2>/dev/null # reload plan + state + knowledge, if beads present
49	```
50
51	If an active plan exists, the handoff must point to it explicitly and state which work unit/phase is in progress.
52
53	### Step 3 — Establish current status
54
55	Be honest and specific about state. Distinguish clearly between:
56
57	- Done & verified — with evidence (tests passing, build green, commit SHAs).
58	- Done but unverified — written but not yet tested/run.
59	- In progress — the exact thing being worked on right now, and where it stopped.
60	- Not started — remaining work.
61
62	Capture the working tree reality so the next agent is not surprised:
63
64	```bash
65	git branch --show-current
66	git status --short
67	git log --oneline -10
68	git diff --stat
69	```
70
71	Note uncommitted changes, stashes, and whether the branch is pushed.
72
73	### Step 4 — Identify required reading
74
75	List every artifact the next agent must read before acting, and for each one say why and what to look for. Categories to sweep:
76
77	- Specs / Issues — the requirements source of truth (GitHub Issue, spec section, DoD).
78	- Design docs — `docs/plans/*-design.md` and any approved design.
79	- Plans — `.beads/plans/active-plan.md`, `docs/plans/*-plan.md`.
80	- Code — the specific files and `file:line` anchors that are the focus of the work, plus any pattern files to imitate.
81	- Tests — the tests that define correctness (failing tests are the spec under TDD).
82	- Config / gates — `.coverage-thresholds.json`, CLAUDE.md rules, CI config that the change must satisfy.
83
84	Prefer precise pointers (`src/foo.ts:120-145`) over whole-file references. If something is short and load-bearing, quote it directly into the handoff so the next agent does not have to hunt.
85
86	### Step 5 — Decide the single next action (`YYY`)
87
88	Pick the one most important, concrete next step. It must be:
89
90	- Actionable — an imperative the agent can start immediately.
91	- Specific — names files, functions, or DoD items.
92	- Bounded — the immediate next move, not the entire remaining roadmap (the rest goes in the document's "Remaining work" section).
93
94	### Step 6 — Write the document
95
96	Create `docs/handoffs/handoff-<YYYY-MM-DD-HHmm>.md` using the template below. Fill every section; write "None" where a section genuinely does not apply rather than deleting it.
97
98	### Step 7 —

People who liked this also viewed

6 picks

Type

paperclip-create-agentCreate new agents in Paperclip with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hSkillsJul 2026157k5
subagent-driven-developmentUse when executing implementation plans with independent tasks in the current sessionSkillsJul 2026154k259k
dispatching-parallel-agentsUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesSkillsJul 2026143k259k
browser-act-skill-forgeForges reusable Skill packages (SKILL.md + scripts) from website exploration via browser-act — no re-exploration later. Use when: user wants a reusable Skill for any website, needs to understand a sitSkillsJul 202685k4.6k
wizardGenerate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each stSkillsJul 202675k182k
wonda-cliUsing the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automationSkillsJul 202666k137