DEC-0023: First-Class Handoff Artifacts

Decision

Handoffs are now a first-class project artifact, not an optional courtesy.

The repo distinguishes between:

• execution prompts: who should do what next
• handoff prompts: what state is being transferred, with git condition, completed work, remaining work, and active risks
• session notes: continuity aids for paused work, not default cross-agent routing

By default, agents create a handoff prompt whenever transfer state matters. If the human explicitly says not to create a prompt for one specific transfer, the agent obeys that override and records the transfer in a session note instead. That override applies only to that one handoff.

Context

The prompt relay system was already the durable project-management substrate, but handoff discipline remained partially implicit:

• AGENTS.md required self-contained prompts and git-state recording for handoffs
• context-health rules already expected a handoff when sessions ran hot
• session notes already existed for continuity

The operational gap was that the repo talked about handoffs more than it implemented them:

• prompts/patterns/handoff.md was referenced but missing
• rules did not cleanly distinguish execution prompts from handoff artifacts
• the human had to remind agents to create "meta" state-transfer records
• one-off human overrides such as "do not prompt this handoff" were not explicitly documented

That made transfer state vulnerable to evaporating into chat memory instead of becoming a durable repo artifact.

Rationale

Execution and transfer are not the same thing.

An execution prompt can describe a task cleanly while still losing critical state:

• which owner is handing work to whom
• whether the worktree was clean or noisy
• what partial progress already exists
• what risks or blockers are still active

The project needs those facts captured automatically, especially when multiple agents share development, prompts are queued in parallel, and orchestration is expected to happen without human babysitting.

The human also needs a legitimate override path for exceptional cases. A one-off "do not prompt this handoff" instruction should work without breaking the general rule that state transfer belongs in durable artifacts.

Consequences

Positive

• Cross-agent transfer state now has a canonical artifact and pattern.
• Agents no longer need a special reminder to create "meta" handoffs.
• Session notes have an explicit, narrow override role instead of silently substituting for prompts.
• Red context pressure now has a documented non-prompt fallback when the human chooses it explicitly.

Tradeoffs

• Agents must spend a little more effort externalizing state during noisy or partial work.
• Prompt counts may rise slightly because state-transfer quality is now explicit infrastructure rather than optional narration.

Implementation

This decision is reflected in:

• AGENTS.md
• .cursor/rules/prompts.mdc
• .cursor/rules/context-health.mdc
• docs/session-notes.md
• prompts/patterns/handoff.md
• scripts/prompt-queue.py

Codex is responsible for stewarding this behavior and for using the override path correctly when the human explicitly chooses it.