# summary

Create a setup-agents handoff record.

# description

Appends a JSON Lines handoff entry to `.setup-agents/state/handoffs.jsonl`.

Handoff records capture role-to-role transfer summaries, ownership, task ids, changed files, risks, and next actions.

# flags.summary.summary

Short handoff summary.

# flags.summary.description

Describe the handoff in one concise sentence.

# flags.task.summary

Task or issue id for this handoff.

# flags.task.description

Associate the handoff with a task id such as `SA-96` or `#96`.

# flags.role.summary

Owning role for this handoff.

# flags.role.description

Record the current role or agent owner responsible for this handoff record.

# flags.profile.summary

Owning setup-agents profile.

# flags.profile.description

Record the setup-agents profile responsible for this handoff record.

# flags.from.summary

Source role or profile.

# flags.from.description

Record who is handing off the work.

# flags.to.summary

Target role or profile.

# flags.to.description

Record who should receive the handoff.

# flags.files.summary

Changed files.

# flags.files.description

Comma-separated list of files relevant to the handoff.

# flags.changed-file.summary

Changed file paths.

# flags.changed-file.description

Alias for `--files`.

# flags.risks.summary

Known risks.

# flags.risks.description

Record known risks, gaps, or review concerns.

# flags.risk.summary

Known risks.

# flags.risk.description

Alias for `--risks`.

# flags.next-actions.summary

Next actions.

# flags.next-actions.description

Record concise next actions for the receiving role.

# flags.next-action.summary

Next actions.

# flags.next-action.description

Alias for `--next-actions`.

# flags.evidence.summary

Related evidence ids.

# flags.evidence.description

Comma-separated evidence record ids that support this handoff.

# flags.acceptance.summary

Acceptance criteria for the receiving role.

# flags.acceptance.description

Quoted, comma-separated acceptance criteria. Text containing commas should be wrapped in quotes, e.g. `"Given X, when Y" , "Then Z"`.

# flags.capability-signals.summary

Runtime capability signals for the receiving role.

# flags.capability-signals.description

Comma-separated signals the next sub-agent should use to activate runtime capabilities,
for example `qa evidence,acceptance criteria coverage,release evidence`.

# examples

- Create a handoff from developer to QA:

  <%= config.bin %> <%= command.id %> --task SA-96 --from developer --to qa --files "src/foo.ts,test/foo.test.ts" --summary "Commands implemented and ready for verification"

# info.created

Handoff recorded: %s (%s)