Cross Project Referrals

Cross-Project Referrals

A referral is a request, bug report, improvement, or note that one handoff-enabled project sends to another. When work in project A reveals something project B needs to do, A sends a referral; B finds it waiting in its .handoff/ the next time it loads context.

Sending — handoff_refer

The sending project must be initialized (.handoff/config.toml present). The target is resolved by target_project_dir (an absolute path, takes precedence) or target_project (matched by project.name against the directories listed in the sender's dashboard.scan_dirs). The target must have a .handoff/ directory.

Key inputs:

• summary — required, a one-line description.
• referral_type — one of improvement / bug / request / info (defaults to request).
• priority — low / medium / high (validated when given).
• details — the body: background and requirements.
• tasks — suggested tasks, each ideally with non-empty done_criteria.
• context — supporting references (e.g. spec_docs).

The referral is written to the target's .handoff/referrals/ with an open status and an ID of the form ref-YYYYMMDD-HHMMSS-<nanoseconds>. The tool then emits non-blocking quality warnings if the referral lacks details, suggested tasks, a priority, context, or spec/doc references, or if a referenced path cannot be found.

Reading — handoff_list_referrals and handoff_get_referral

handoff_list_referrals returns summaries only — id, source_project, referral_type, summary, priority, status, created_at — optionally filtered by status (open / acknowledged / resolved).

{
  "referrals": [
    {
      "id": "ref-20260624-101500-123456789",
      "source_project": "other-project",
      "referral_type": "request",
      "summary": "Please update the API for compatibility",
      "priority": "high",
      "status": "open",
      "created_at": "2026-06-24T10:15:00+00:00"
    }
  ],
  "total": 1
}

To read the full body — details, suggested tasks with their done_criteria, and context — use handoff_get_referral with the referral's referral_id. You may pass a unique ID prefix; if it matches exactly one referral it is returned, and an ambiguous prefix is rejected with a request for the full ID.

{
  "id": "ref-20260624-101500-123456789",
  "source_project": "other-project",
  "source_project_dir": "/abs/path/to/other-project",
  "created_at": "2026-06-24T10:15:00+00:00",
  "referral_type": "improvement",
  "summary": "Please update the API for compatibility",
  "details": "Background and requirements…",
  "priority": "high",
  "tasks": [
    {
      "title": "Implement a compatibility layer",
      "priority": "high",
      "done_criteria": [
        { "item": "Finalize the design" },
        { "item": "Implement and test" }
      ]
    }
  ],
  "context": { "spec_docs": ["docs/api.md"] },
  "status": "open"
}

handoff_get_referral is the only way to read a referral's body through the MCP — don't read .handoff/referrals/*.json directly.

Updating status — handoff_update_referral

Advance a referral through its lifecycle: open → acknowledged → resolved. Both referral_id and status are required; an invalid status is rejected. The status is stored in the referral's filename suffix and renamed on update.

Typical flow

1. A discovers B needs a change → handoff_refer (with details, tasks, done_criteria, context).
2. B runs handoff_load_context and sees the unread referral → reads it with handoff_get_referral.
3. B acknowledges it (handoff_update_referral → acknowledged), turns the suggested tasks into real tasks via handoff_update_task, and resolves it (handoff_update_referral → resolved) when done.