Handoffs

Handoffs

Authoritative rule: agents/rules/handoffs.md · Convention: handoffs/README.md

TL;DR

File-based cross-agent dispatch. Used when a task spans sessions, needs structured reports back, or touches shared state requiring explicit human gates.

handoffs/active/<YYYY-MM-DD-slug>/
├── round-01-prompt.md   (dispatcher writes)
├── round-01-result.md   (executor writes)
├── round-02-prompt.md
├── round-02-result.md
└── ...

Slash commands:

• /handoff-open <slug> "<description>" — opens round 01 prompt.
• /handoff-result <slug> — executor scaffolds result for the latest round's prompt.

Closed threads move to handoffs/archive/<slug>/.

When to handoff vs. issue

	Handoff	Issue
Surface	Dispatcher → executor brief	Task tracker entry
Granularity	Per-round (typically one ship)	Per task (multi-round)
Format	Heavyweight (template + frontmatter + gates)	Lightweight (body + comments)
When	Dispatching cross-agent work with destructive phases	Anything that will outlive the session

An issue may have zero, one, or many handoff rounds against it. A handoff thread always references its issue in the prompt frontmatter (tracks: noetl/ai-meta#NN).

Cross-link to dashboard

When a handoff thread is meaningful to the ecosystem (e.g. multi-day cross-repo work), reference it from the relevant Umbrella page under "Recent activity" with the slug.

See the Sessions Log for the chronological session record that includes handoff opens / closes.