Skip to main content

Handoff Pack First

Handoff Pack First is a feature-flagged workflow for newly flagged initiatives. It keeps the classic PRD, Delivery Plan, Linear, blueprint, and implementation-pack workflow available for existing and unflagged initiatives.

The flagged flow is:

Add Context -> Resolve Gaps -> Confirm Targets -> Review Handoff Packs -> Approval PR -> Publish

When This Mode Applies​

The workspace uses this mode only when handoff_pack_first_workflow_enabled is enabled and the initiative is created with workflow_mode = "handoff_pack_first". The workflow mode is stored on the initiative, so later setting changes do not silently move an initiative between workflows.

Classic initiatives still use PRD review, Technical Discovery, draft Delivery Plans, explicit Send to Linear, blueprint or no-blueprint gates, and prepared implementation packs.

Daily Workflow​

  1. Add source context through the UI, Slack, email, or files.
  2. Review Handoff Pack readiness, blockers, missing context, and gap questions.
  3. Answer targeted questions when they improve pack usefulness.
  4. Confirm or amend repo targets and coordination targets.
  5. Generate draft Handoff Packs from confirmed or amended targets.
  6. Review generated files, source refs, requirement coverage, blockers, and stale state.
  7. Create or update an approval PR containing the draft pack files.
  8. Refresh approval PR status after GitHub review or merge.
  9. Publish approved, non-stale packs only when the team chooses destinations.

Gate Boundaries​

Draft Handoff Pack generation in this mode does not require:

  • PRD generation.
  • PRD approval.
  • Delivery Plan generation.
  • Delivery Plan acceptance.
  • Generated tasks.
  • Work Packages.
  • Linear issue creation.

The source-linked evidence layer is the planning source of truth. Generated PRDs, technical requirements docs, and work breakdowns are optional exports from the same context snapshot. They are useful for communication, but they do not unlock or block pack generation.

Approval And Publishing​

Approval PRs and publication are separate.

  • Approval PRs contain draft Handoff Pack files for review in a planning or blueprint repository.
  • Approval or merge marks covered, non-stale packs eligible for publication.
  • Publication is explicit and destination-scoped.
  • Supported destinations are download, target repo PR, Linear update, and Slack notification.
  • Target repo publication creates or reuses a reviewable draft PR and never auto-merges it.
  • Linear publication updates explicitly selected existing issues; it does not create issues or become a prerequisite.
  • Slack publication sends a notification and does not block other selected destinations.
  • Download remains available as a fallback when external destinations fail.

Rollback​

Set handoff_pack_first_workflow_enabled=false at the environment, organisation, or team setting layer to stop new Handoff Pack First actions.

During rollback:

  • Existing Handoff Pack First records remain readable from the persisted workflow mode.
  • The UI exposes workflow.handoffPackFirst.policy.readOnly = true.
  • Gap question refreshes and answers, target edits, draft pack generation, approval PR create or sync, publication, and optional artefact generation are blocked.
  • Existing snapshots, targets, packs, approval reviews, publication records, optional artefacts, markdown exports, and download bundle links remain readable.
  • No automatic migration runs in either direction.

Operation creation and rendering can be separately reduced with initiative_operation_creation_enabled=false or initiative_operation_rendering_enabled=false when operational progress reporting needs rollback, but those flags do not migrate or delete Handoff Pack First records.