Initiatives

Initiatives are multi-phase projects that coordinate multiple Work Units (WUs) across lanes. This page covers the Software Delivery pack view: when to create one and how the commands relate to the rest of the pack.

Note

Running an initiative end-to-end — control-plane lifecycle, state machine, artifact bundle, capacity + integrity, SDK contract — lives in its own top-level section: Orchestration. This page stays focused on “do I need an initiative for this?” and “how do I create one?”.

When to use an initiative

Create one when all of these are true:

• The feature spans multiple WUs (≥ 3–4).
• Work crosses multiple lanes (Framework + UI + Ops, etc.).
• There are dependencies between WUs.
• You need phased rollout (e.g. backend → frontend → launch).

If a task fits in a single WU, don’t create an initiative. The orchestration layer is coordination overhead you only want when coordination is the problem.

Creating an initiative

Initiative planning and orchestration are owned by the Software Delivery Pack. Programmatic consumers should import @lumenflow/packs-software-delivery/initiatives. The former @lumenflow/initiatives package remains only as a deprecated forwarding shell during the v6 package-graph transition.

pnpm initiative:create \
  --slug user-authentication \
  --title "User Authentication System" \
  --priority P1 \
  --owner "Team Alpha" \
  --target-date 2026-02-01

This writes docs/operations/tasks/initiatives/INIT-001.yaml. Commands that operate on initiatives (initiative:edit, initiative:add-wu, initiative:status, orchestrate:initiative, orchestrate:init-status) are documented in the CLI reference.

Linking WUs

Use wu:create --initiative INIT-001 when creating a WU under an initiative. That links the WU through the WU YAML initiative field, which is what initiative:status and orchestration use to derive membership.

The initiative YAML wus array is optional metadata. initiative:add-wu can backfill or repair that metadata for existing WUs, but it is not the authority for whether a WU belongs to an initiative.

Lifecycle commands write through push-only micro-worktrees. If a just-created --initiative WU does not appear in local status output, your local main checkout may simply be behind origin/main; from a clean main checkout, run pnpm git:sync-main rather than raw git pull.

Running one

Once WUs exist under the initiative, orchestration is the feature area that carries you the rest of the way:

Orchestration overview The evidence-based control plane — plan, handoff, execution, reconciliation, finish, status.

Orchestration lifecycle The six phases orchestration separates, with the evidence each phase consumes and emits.

State machine The 13-value orchestration state vocabulary and next-safe-action priorities.

Artifact bundle plan.json / launch.json / status.json / per-WU handoffs, plus logical_wave vs launch_attempt.

Capacity + integrity --max-active-workers, contamination detection, stalled worktrees, and how reconciliation refuses to advance unsafely.

Control-plane SDK @lumenflow/control-plane-sdk — the shared contract powering local, cloud, and MCP surfaces.