---
name: card-handoff-contract
description: "Use when finishing a kanban card; the handoff contract."
version: 1.0.0
author: Joan (for Ian Kellar)
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [kanban, handoff, completion, metadata, artefacts, process]
    category: devops
    related-skills: [kanban-research-report-pipeline, hermes-kanban, multi-agent-profiles]
---

# Card handoff contract

## When to Use

- You are creating a kanban card: pin this skill on it, so the worker receives the
  handoff rules rather than being expected to know them.
- You are a dispatched worker finishing a card of any kind: complete the handoff as
  below before your final message.
- You are auditing a wave or recovering a card whose output looks missing: check the
  three channels below in order before assuming the work was not done.

Pin this skill on any card you create. Applies to every dispatched worker.

A card is not finished when the work is done. It is finished when the work is
recoverable by whoever runs next, off the board alone.

1. **Metadata.** Pass the card's requested schema as structured metadata on the
   completion call. An empty metadata object is a failed handoff, not a formatting
   detail. Where the brief names a schema, the metadata must carry those fields.
2. **File.** Write the same object to `completion.json` in your workspace.
3. **Attach.** Attach every deliverable with `kanban_attach`, or from the
   orchestrator with `hermes kanban attach <card> <path>` (it takes a file path, no
   base64 needed). Naming a path in metadata is not enough: task workspaces are
   pruned, and metadata describing a lost file still reads as complete.

Order: attach first, complete second.

4. **If the lifecycle call drops the metadata**, re-post the object as a comment and
   say in the summary line that the metadata channel was empty, so the next reader
   knows where to look. Do not let a lost payload pass silently.
5. **Counts.** Report the counts the brief asked for, including zeros, and name what
   was never checked. Zero matches is not success when required content was never
   read.

## Why a skill and not the profile contract file

Worker profiles do **not** load their `AGENTS.md`. Verified 16 Oct 2026: the config
key `profile_context_file` appears nowhere in the product code, project-context
discovery reads the working directory chain (a task workspace has no `AGENTS.md` and
is not a git repo), and a research worker probed with a distinctive phrase answered
`NOT IN MY CONTEXT`. Every worker operating contract written into a profile
`AGENTS.md` has been inert.

The two channels that do reach a headless worker:

- **Pinned skills.** The dispatcher passes one `--skills <name>` flag per pinned
  skill, and the CLI folds their content into the prompt before the first turn. This
  is why a card that pins a skill its profile cannot resolve dies at init, and why
  pinning is the reliable way to put a rule in front of a worker.
- **`SOUL.md`**, which is always included.

Anything a worker must obey belongs in one of those two places, or in the card body.

## Audit

`~/.hermes/skills/devops/kanban-research-report-pipeline/scripts/wave-audit.py`
flags cards whose run metadata is empty, whose artefacts are unattached or missing,
and whose comment trail is absent. Run it after a wave and before its consumer, not
after. It reads the database, so a worker's own claim cannot satisfy it.