01Artifact
Begin with the human action at the other end.
“Save the output” is vague. Name the thing: a client email to approve, a Slack update to post, a pull-request description to submit, an incident brief to hand over, a decision record to retain, or a command set to run. Then name the audience and the next action.
The artifact should be readable without the agent session. Replace “as discussed above” with the actual decision. Replace “tests passed” with which checks ran when that detail matters. Remove tool chatter, failed drafts, and branches of reasoning that do not belong in the deliverable.
02Shape
Use a recipe when missing a field would make the handoff weaker.
Typed recipes give Slack updates, client emails, GitHub pull requests, incident summaries, decisions, and command sets explicit fields. That helps the agent remember an ask, test plan, risk, impact, or warning. Use free-form Markdown when the deliverable does not fit a recipe or the structure would add noise.
Save a DraftRelay incident summary for Payments. Status: mitigated. Include impact, a short UTC timeline, confirmed root cause, follow-up owners, and unresolved questions. Mark unverified details as unverified.
03Evidence
Attach source context without pretending it is proof.
When a client knows the context, it can supply its name and version, agent or model, session, working directory, repository root and remote, branch, commit, dirty-tree state, verification status, a verification summary, and referenced file lines. Missing fields remain unknown.
Ask for provenance that helps review. A client email rarely needs a local path. A PR description benefits from branch, commit, tests, and referenced files. An incident brief may need source systems and timestamps, but not a raw log dump. Never place credentials in provenance fields.
04Lifecycle
Let the status communicate delivery, not author confidence.
new means the artifact arrived. reviewed means a human checked it. copied means a destination copy action succeeded. done means the handoff is complete and can leave the active outbox. Revising an item returns it to new because the current text has changed.
A project can require human review before copy, require acknowledgement of secret findings, restrict destinations, and decide whether a copy marks an item copied or done. These policies make repetitive handoffs consistent without letting the agent send anything automatically.
05Failure modes
Most bad artifacts are too broad, too early, or too certain.
- Too broad: a transcript or research dump forces the recipient to repeat the agent’s synthesis.
- Too early: a saved plan is presented as an outcome before implementation or verification finishes.
- Too certain: inferred facts and unrun tests are written as confirmed.
- Too context-dependent: the copy refers to terminal lines or files the recipient cannot see.
- Too automatic: destination formatting is trusted without a final human review.