---
name: handoff
description: Create or resume compact Markdown and JSON task handoff artifacts for transferring work between agents, sessions, or sub-agents.
---

# Handoff Workflow (/handoff)

Use `/handoff` when a task should continue in another agent, another session, or an isolated sub-agent context.

T-C06 handoff output is dual-format:

- Markdown for `HUMAN_RESUME`.
- JSON for `AGENT_RESUME`.
- Artifact Bus entry (`kind: handoff`) for coordinator indexing when `.agent/artifacts/scripts/artifact-bus.js` exists.

## Usage

```text
/handoff create "short task focus"
/handoff resume .agent/handoffs/YYYYMMDD-HHMMSS-short-task-focus.md
/handoff resume .agent/handoffs/H-YYYYMMDD-HHMMSS-short-task-focus.json
```

## CREATE

1. Read the current task source:
   - `AGENTS.md`
   - `.agent/rules/core-principles.md`
   - `.agent/rules/code-standards.md`
   - `.agent/plans/task-progress.md` when it exists
   - `.agent/plans/context-manifest.json` when it exists
2. Inspect repository state:
   - `git status --short`
   - current branch
   - relevant changed files
3. Record a Runtime Continuity checkpoint before writing the handoff:
   ```bash
   PROJECT_NAME=$(basename "$(pwd)")
   node .agent/skills/runtime-continuity/scripts/index.js checkpoint \
     --project "$PROJECT_NAME" \
     --gate agent \
     --type handoff \
     --phase handoff \
     --message "Creating handoff for <task-or-focus>"
   ```
4. Create `.agent/handoffs/` if it does not exist.
5. Write a compact Markdown handoff using the `handoff` skill template.
6. Write the matching JSON payload using `.agent/handoffs/handoff.schema.json` semantics.
7. Reference existing artifacts by path or URL instead of copying their contents.
8. Validate the JSON payload:
   ```bash
   node .agent/handoffs/scripts/handoff-protocol.js validate --payload-file .agent/handoffs/H-YYYYMMDD-HHMMSS-focus.json
   ```
9. When Artifact Bus exists, publish the JSON payload:
   ```bash
   node .agent/handoffs/scripts/handoff-protocol.js publish --payload-file .agent/handoffs/H-YYYYMMDD-HHMMSS-focus.json --markdown-path .agent/handoffs/YYYYMMDD-HHMMSS-focus.md --agent-id coordinator
   ```
10. End the Markdown with a `Resume Prompt` that the next agent can follow directly.
11. If Management API exists, append a `handoff_created` Run event for the active task:
    ```bash
    cortex-agent runs checkpoint --project . \
      --run-id R-<task-id> \
      --status running \
      --phase handoff \
      --type handoff_created \
      --message "Handoff artifact created"
    ```

## RESUME

1. Read `AGENTS.md` and required `.agent/rules/` files.
2. Run Runtime Continuity resume bundle first:
   ```bash
   PROJECT_NAME=$(basename "$(pwd)")
   node .agent/skills/runtime-continuity/scripts/index.js resume-bundle --project "$PROJECT_NAME"
   ```
3. If the input is Markdown, read the requested handoff document.
4. If the input is JSON, run:
   ```bash
   node .agent/handoffs/scripts/handoff-protocol.js resume-prompt --payload-file <handoff.json>
   ```
5. Check `git status --short` before changing files.
6. Read the referenced plans, Artifact Bus state, source files, tests, and docs.
7. Compare the handoff, Runtime Continuity archive, and current repository state.
8. For writable continuation, acquire required Progress Lock scopes when available.
9. Continue from `Next Steps` or `next_action`, or report conflicts if the handoff is stale.
10. If Management API exists, update Run journal with `status=running`, `phase=handoff`, and a `state_changed` event before writable continuation.

## Quality Bar

- The handoff must be useful without access to the previous conversation.
- It must be small enough to paste into a new agent context if needed.
- It must preserve decisions, constraints, verification state, and next actions.
- It must avoid duplicating plans, PRDs, commits, diffs, ADRs, and API docs.
- JSON handoff payloads must be valid before publish.
- Artifact Bus publish is skipped only when the bus is not installed or the task deliberately stays human-only.

## Session Transition

- After publishing a handoff, pause the source owner session with `sessions pause --session-id <id> --gate handoff --activity "Handoff published"`.
- On resume, the target opens its own session or heartbeats an existing owner-matched session; it must not refresh the source owner heartbeat.
- Session transition evidence must reference the handoff and active Run; stale remains a read-time derived status.

## Recording Points

`/handoff` owns activity at the publish boundary. Record a capture receipt after the handoff JSON is published to the artifact bus:

```bash
# After handoff JSON is published
node .agent/skills/activity-recording/scripts/index.js record-receipt \
  --kind capture \
  --source /handoff \
  --activity-refs ACT-handoff-<HANDOFF_ID>-publish \
  --availability available \
  --redaction not_applicable \
  --dedupe-key "handoff:<HANDOFF_ID>:capture"

# When the target agent resumes (optional)
node .agent/skills/activity-recording/scripts/index.js record-event \
  --kind coordination \
  --source /handoff \
  --summary "Handoff <HANDOFF_ID> resumed by <target-agent>" \
  --actor-type workflow \
  --actor-id /handoff \
  --dedupe-key "handoff:<HANDOFF_ID>:resume"
```

If the helper is missing or recording is unavailable, continue with the legacy workflow behavior and skip the call. Do not invent receipts.