Handoff
@maphew/handoffv2026.10.15.4
01README
Exact-state engineering handoffs. Captures a deterministic, secret-free snapshot of Git worktree state plus the authoritative active Bead, records the narrative (goal, scope, commands, decisions, next safe step, forbidden operations), and writes a queryable handoff resource and a markdown report.
02Release Notes
Relicense from AGPL-3.0-only to MIT.
03Behaviors
@maphew/handoffv2026.10.15.3src/handoff.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| repoDir? | string | Worktree to capture. Defaults to the current directory so the behavior is portable across machines and worktrees. |
| gitCommand? | string | Git executable |
| bdCommand? | string | Beads executable |
| bdDir? | string | Working directory for bd (auto-discovers .beads/) |
fn capture(beadId: string, baseRef?: string, goal?: string, scope?: string, completed?: array, excluded?: array, commands?: array, evidence?: array, decisions?: array, openQuestions?: array, nextSafe?: string, forbidden?: array, notes?: string)
Snapshot Git and Bead state, write a handoff resource and markdown report
| Argument | Type | Description |
|---|---|---|
| beadId | string | Active Bead identifier, e.g. myswamp-imx |
| baseRef? | string | Base ref to diff against, e.g. origin/main. Resolved to a commit SHA and merge-base. |
| goal? | string | Accepted goal for this work |
| scope? | string | Scope still in play |
| completed? | array | Completed scope items |
| excluded? | array | Scope explicitly excluded |
| commands? | array | Commands run and their exact outcomes |
| evidence? | array | Locations of test/review evidence |
| decisions? | array | Decisions already made |
| openQuestions? | array | Open hypotheses, uncertainty, owner decisions outstanding |
| nextSafe? | string | The single next safe command or action for the successor |
| forbidden? | array | Operations explicitly not to perform |
| notes? | string | Any other durable context |
fn resume(beadId: string)
Read the newest handoff for a Bead and write a cold-start resume brief
| Argument | Type | Description |
|---|---|---|
| beadId | string | Bead whose newest handoff to resume |
fn list(limit?: number)
Catalogue stored handoffs for this behavior instance
| Argument | Type | Description |
|---|---|---|
| limit? | number | Maximum catalogue entries to return |
Resources
handoff(30d)— Exact Git + Bead state and narrative for a resumable handoff
resume(7d)— Cold-start summary re-surfaced from a stored handoff
catalog(1d)— Catalogue of stored handoffs for this behavior instance
Files
report(text/markdown)— Markdown handoff / resume brief
04Previous Versions
2026.10.15.3AGPL-3.0-only
Fix leading-space corruption of git status --porcelain -z output.
2026.10.15.2AGPL-3.0-only
Fix duplicate data instance name: report file now distinct from the handoff resource.
2026.10.15.1AGPL-3.0-only
Initial release: capture/resume/list methods for exact-state handoffs.
05Stats
A
100 / 100
Downloads
6
Archive size
17.2 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
deno-command1 accepted
Spawns a subprocess with Deno.Command().
- models/src/handoff.ts:476 — no reason given
07Platforms
08Labels