handoff-protocol

Executes PM-to-engineering spec handoffs via owner flips with pre-flight gates and bitemporal history.

3|2|Updated Aug 24, 2026
One-click install
npx skills add https://github.com/hero-engine/hero --skill handoff-protocol-hero-engine
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: handoff-protocol
Source: https://github.com/hero-engine/hero/tree/main/domains/pm/skills/handoff-protocol
Command: npx skills add https://github.com/hero-engine/hero --skill handoff-protocol-hero-engine

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Handing a product spec from PM to engineering often loses context through copied tickets, paraphrased packets, or duplicated artifacts. This Skill defines a formal handoff protocol where the same spec artifact changes owner from pm to engineering, with blocking pre-flight checks and an append-only ownership history, so nothing is lost or duplicated at the boundary. ## Core Features & Use Cases - Pre-flight gates: Blocks handoff unless the spec is in-review, currently PM-owned, has EARS-format acceptance criteria, and an explicit Out-of-Scope section; warns on missing PRD or initiative links. - Atomic owner flip: Runs hero spec set-owner <slug> engineering, which appends a bitemporal owner_history row that serves as the cross-domain edge — no separate handoff edge or second spec is created. - Hand-back handling: Detects when engineering flips ownership back with a handed_back_reason, routes the spec for revision, and re-flips after review, preserving the full transition history. - Use Case: A PM finishes refining a feature spec, the reviewer passes it, and the handoff coordinator verifies the gates, flips ownership, and confirms engineering's agent claims it via /deliver within the expected window. ## Quick Start Ask the agent to hand off the spec to engineering, for example: run the handoff protocol on the 'session-retry' spec and verify engineering picks it up.

Frequently Asked Questions about handoff-protocol

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I hand off a spec from PM to engineering?▼

Run the handoff on a spec that has passed review; the coordinator pre-flights it and runs `hero spec set-owner <slug> engineering`. The same spec artifact carries through unchanged, and engineering's agent claims it via `/deliver <slug>`.

What checks block a spec handoff to engineering?▼

Four blocking gates apply: status must be `in-review`, owner must currently be `pm`, acceptance criteria must exist in EARS format, and Out-of-Scope must be populated. Missing PRD or initiative links only produce warnings.

Does the handoff create a separate engineering spec?▼

No. Under the unified type model there is one feature artifact shared across the owner flip. No `/design` call, no second spec, no `kind: handoff` graph edge, and no handoff packet are created.

What happens if engineering hands the spec back to PM?▼

Engineering flips owner back to `pm` with a `handed_back_reason` field explaining the gap. PM addresses the reason, the reviewer passes the spec again, and the flip reruns, with all transitions preserved in the append-only owner_history.

Why did the handoff succeed but engineering never picked up the spec?▼

The owner flip is asynchronous from engineering's claim. Common causes are engineering being offline, no engineer agent available, or a PM-only workspace; the user can manually invoke `/deliver <slug>` to force pickup.