cross-org-handoff

name	cross-org-handoff
description	Create a formal XD- handoff file between HQ and Engineering. Covers packet shape selection, YAML schema, filing, and memory log requirements.
when_to_use	When any HQ or Engineering agent needs to formally transfer a decision, plan, request, or deliverable to the other org. Required any time the outcome must be logged, tracked, or acknowledged across the org boundary.
when_to_skip	Internal HQ-only or Engineering-only communications with no cross-org dependency. Informal verbal alignment that doesn't need a logged artifact. Do not create an XD- file just to document a status update with no action required.
version	1.0
last_updated	"2026-04-23T00:00:00.000Z"
applies_to	both

Cross-Org Handoff Procedure

Purpose

Cross-org work fails silently when decisions exist only in conversation. This skill enforces a formal artifact — a YAML file with a stable XD- ID — whenever something material moves between HQ and Engineering. It defines which packet shape to use, what fields are required, and what gets logged where. Without this discipline, a plan approved in a roundtable may never reach Engineering, or an Engineering constraint may never reach the founder's decision record.

Pair With

• memory-entry — material XD- decisions require an HQ- entry in bound hq_business_memory_log.md
• roundtable — roundtable outputs that cross the org boundary are common handoff triggers
• inbox-processing — incoming cross-org items found in inbox route through this skill

Onboarding gate (BAM Product)

When John (HQ Chief of Staff) is operating in the portable method pack, do not file material cross-org handoffs that route Mike to Engineering execution until ONBOARDING.md at pack root is Stable or a Founder waiver is recorded there — see org_hq/agents/core/hq-chief-of-staff.md § Onboarding gate (BAM Product). Complete first-contact onboarding first; park deferred work in ONBOARDING.md.

Packet Shapes

Shape	Where	Use when
HQ handoff table schema	protocols/hq_handoff_schema_v1.md	Short, human-readable packet: objective, in_scope, out_of_scope, next_action — BAM Product: also from_agent_spec_id + to_agent_spec_id (registry); from_ho_key / to_ho_key optional mirror — see § BAM Product pack in schema
XD file artifact (this skill)	Bound org: shared_context/handoff_*.yaml · Public method pack: pack_private/handoff_*.yaml (gitignored — PACK_PRIVATE.md)	Formal XD- file — pair with cross_org_decisions.md + hq_business_memory_log.md (Company). Do not commit Company operational handoffs to the pack’s public shared_context/.

Checklist

Priority	Item	Notes / Evidence
CRITICAL	XD- ID assigned before filing — never file without one	Format: XD-NNN or XD-YYYYMMDD-NNN; check cross_org_decisions.md for next available ID
CRITICAL	Correct packet shape selected (HQ handoff table vs XD file artifact)	See Packet Shapes table above — do not paste XD schema into a sync doc or vice versa
CRITICAL	BAM Product pack: from_agent_spec_id and to_agent_spec_id on every new handoff YAML — ids from agent_spec_registry.yaml; unknown id = validation failure	Run python3 scripts/validate_pack_handoff_yaml.py --strict before committing examples
CRITICAL	Optional from_ho_key / to_ho_key — legacy mirror for humans / Company BAM; not sufficient alone for new product routing	Per hq_handoff_schema_v1.md § BAM Product pack
CRITICAL	Material decisions logged in bound hq_business_memory_log.md — YAML alone is not a substitute	Evidence: HQ- or MEM- row referencing the XD- ID
HIGH	YAML filed using the correct naming convention	handoff_{xd_id}_{direction}_{date}.yaml in bound shared_context/ or pack_private/ on the method pack — never Company-only packets in public shared_context/
HIGH	cross_org_decisions.md updated with this XD- entry	Evidence: row present with status, direction, and summary
HIGH	If responding to an existing handoff: original handoff status updated to closed	Evidence: original YAML status field changed
MEDIUM	Receiving org creates an acknowledgment file when handoff is actioned	ack_{xd_id}_{org}_{date}.yaml — not required at creation, but track follow-through
LOW	project_status_sync.md updated if handoff changes the live cross-org state	Relevant for milestone completions or plan approvals that shift project phase

Anti-Patterns

• The wrong shape: Using the HQ handoff table schema (hq_handoff_schema_v1.md) when a formal XD- artifact is needed — or the reverse. The table schema is for human-readable inline YAML in docs and emails. The XD file schema is for shared_context/ artifacts that get logged and tracked. They are not interchangeable. Public product: operational XD YAML lives in pack_private/ or your Business repo — not in scrubbed shared_context/.

• YAML without a memory entry: Filing a handoff YAML for a material decision but skipping the hq_business_memory_log.md row. The YAML exists on disk; the decision is invisible to any agent reading the memory log. Both are required.

• Missing routing ids (product pack): Omitting from_agent_spec_id / to_agent_spec_id on new YAML while relying only on from_ho_key / to_ho_key. HO keys are a mirror, not the canonical routing key for benai-agent-method-public — use registry ids; validate with validate_pack_handoff_yaml.py --strict.

• Orphaned response: Creating a response handoff without closing the original. The original stays open indefinitely. Always update the source handoff's status field when responding.

• Verbal cross-org: Communicating a material cross-org decision in conversation or a roundtable minute without creating an XD- artifact. The decision exists only as narrative. If it crosses the org boundary and has action requirements, it needs an XD- file.

Output Artifact

A completed run of this skill produces a YAML file in bound shared_context/ or pack_private/ (method pack — see PACK_PRIVATE.md). Naming convention: handoff_{xd_id}_{direction}_{date}.yaml

Example: handoff_xd_NNN_hq_to_engineering_milestone_YYYY-MM-DD.yaml

---
handoff_id: XD-NNN
direction: hq_to_engineering | engineering_to_hq
type: approval | request | corrective_roadmap | planning_handoff | milestone_completion
title: "Short descriptive title"
created_utc: "YYYY-MM-DDTHH:MM:SSZ"
status: open | delivered | acknowledged | closed
priority: P0 | P1 | P2
# Canonical routing (BAM Product — required on new YAML)
from_agent_spec_id: hq_chief_of_staff
to_agent_spec_id: engineering_orchestrator
# Optional legacy mirror (HO keys — not sufficient alone)
from_ho_key: john
to_ho_key: mike
created_by: John — HQ Chief of Staff
target: Mike — Engineering Orchestrator

summary: >
  Multi-line description of what this handoff contains and why.

artifacts_delivered:
  - path: "relative/path/to/artifact.md"
    type: roundtable_minutes | plan | spec | agent_update
    summary: "One-line summary"

actions_required:
  - "Action item 1"
  - "Action item 2"

conditions:
  - "Condition 1"

blocking: true | false
blocks: "What this blocks if true"

Stop Conditions

• No XD- ID available and cross_org_decisions (live or pack .STUB.md) is not accessible → do not file; flag to founder
• Target org or agent is ambiguous → resolve agent_spec_id from agent_spec_registry.yaml (and roster narrative from ../../../shared_context/agent_directory.md) before filing
• Handoff requires blocking a downstream dependency and the blocks field is unclear → stop, define blocks explicitly before sending

Filing

1. YAML file → bound shared_context/handoff_{xd_id}_{direction}_{date}.yaml or pack_private/handoff_{xd_id}_{direction}_{date}.yaml
2. Log entry → bound hq_business_memory_log.md (use memory-entry skill). Pack stub: shared_context/hq_memory_log.md is not for operational HQ- rows.
3. Decision row → ../../../shared_context/cross_org_decisions.STUB.md (or live cross_org_decisions.md when bound)
4. If responding to a prior handoff → update original YAML status: closed
5. If project phase changes → ../../../shared_context/project_status_sync.STUB.md (or live project_status_sync.md when bound)