Handoff System

Purpose

Define first-class handoff artifacts that capture session context, decisions, and next steps for seamless transitions between work sessions or between human and AI collaborators.

Context loss between work sessions is one of the biggest productivity drains in software development. When a developer (or AI agent) picks up work, they spend significant time reconstructing what was done, what decisions were made, and what comes next. Handoff documents formalize this context transfer, but without tooling support they are inconsistently created and often incomplete. A built-in handoff system ensures that context is captured systematically and enriched with data from other tools.

Design Rationale

First-Class Artifact

Making handoffs a first-class artifact type rather than ad-hoc notes is a Type 1 decision. This ensures they have consistent structure, are stored in predictable locations, and can be enriched by plugins (e.g., beads issues, git status, openspec changes).

Template-Based Generation

Handoffs are generated from templates with frontmatter metadata. This is a Type 2 decision — templates can evolve, but the pattern of structured generation with metadata is foundational.

Plugin Enrichment

The handoff generation process calls plugin hooks to gather contextual data. This means a handoff can automatically include:

Open beads issues and their status
Recent git commits and uncommitted changes
OpenSpec changes in progress

Scope and Requirements

This spec covers the handoff artifact format, generation command, and plugin integration points.

Non-Goals

Automatic handoff generation (handoffs are explicitly created by the user)
Handoff consumption or parsing by other tools
Multi-format output (PDF, HTML, etc.)
Collaborative editing of handoffs

Requirement: Handoff Format

Handoffs SHALL be markdown files with structured frontmatter, including dedicated sections for operational nuances that serve as high-signal input to wai reflect.

Scenario: Handoff file structure

WHEN a handoff is generated

THEN it follows this format:

---
date: 2026-01-22
project: my-project
phase: implement
agent: claude
---

# Session Handoff

## What Was Done
<!-- Summary of completed work -->

## Key Decisions
<!-- Decisions made and rationale -->

## Gotchas & Surprises
<!-- What behaved unexpectedly? Non-obvious requirements? Hidden dependencies? -->

## What Took Longer Than Expected
<!-- Steps that needed multiple attempts. Commands that failed before the right one. -->

## Open Questions
<!-- Unresolved questions -->

## Next Steps
<!-- Prioritized list of what to do next -->

## Context
<!-- Plugin-enriched context (beads, git, etc.) -->

Requirement: Handoff Generation

The CLI SHALL provide a command to generate handoff documents.

Scenario: Create handoff

WHEN user runs wai handoff create <project>
THEN the system generates a handoff from the default template
AND enriches it with data from enabled plugins
AND stores it in .wai/projects/<project>/handoffs/YYYY-MM-DD-session-end.md

Scenario: Handoff with plugin data

WHEN generating a handoff with the beads plugin enabled
THEN the Context section includes open beads issues and their status
WHEN generating a handoff with the git plugin enabled
THEN the Context section includes recent commits and uncommitted changes

Requirement: Handoff Storage

Handoffs SHALL be stored in the project’s handoffs directory with date prefixes.

Scenario: Handoff location

WHEN a handoff is created for project “my-app”
THEN it is stored at .wai/projects/my-app/handoffs/YYYY-MM-DD-session-end.md
AND multiple handoffs per day are differentiated by suffix

Requirements

Requirement: Pending-Resume Signal

wai close SHALL write a .pending-resume file to the project directory after every successful handoff creation, enabling wai prime to detect resume context without requiring the user to manually open the handoff.

Scenario: Signal written on close

WHEN wai close successfully creates a handoff
THEN the system writes .wai/projects/<project>/.pending-resume
AND the file contains the path to the new handoff, relative to the project directory (e.g. handoffs/2026-02-24-session-end.md)

Scenario: Signal overwritten on repeated close

WHEN user runs wai close more than once (same day or different days)
THEN the .pending-resume file is overwritten with the path of the newest handoff

Requirement: Handoff Decision-Matrix Summary

When the project has a decision matrix, handoffs SHALL additionally include a decision-matrix summary: the problem statement, the selected approach with rationale (or “not decided yet”), the matrix directory link with cell completion count, and the scaffolded design doc link when a decision exists.

Scenario: Handoff includes matrix summary

GIVEN a project with a matrix whose decision.md records a decision
WHEN a handoff is generated
THEN it includes the problem statement, the selected approach with rationale, and links to the matrix directory and the design doc

Scenario: Handoff without a matrix

GIVEN a project that never initialized a matrix
WHEN a handoff is generated
THEN no matrix section is added and the format is unchanged

Keyboard shortcuts

wai