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 @hellmai/lumenflow-packs-software-delivery/initiatives. The former @hellmai/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 the initiative YAML file. 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 <initiative-id> 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.

Membership is decided before the claim

A WU’s initiative field is one leg of the identity triple id ↔ initiative ↔ title, which is canonical on origin/main. While a WU is claimed, that membership is immutable — wu:edit refuses the mutation, wu:done refuses the resulting divergence at landing, and so do initiative:add-wu and initiative:remove-wu.

For the two membership commands, “claimed” means in_progress, blocked, waiting, or the legacy claimed alias — blocked and waiting count because neither releases the claim: the worktree and claimed_branch survive both. wu:edit’s own guard is narrower (in_progress plus the legacy alias) and has not been widened.

Caution

Attaching or detaching a claimed WU is refused before anything is written, whenever the change would actually move its membership. Neither the WU YAML nor the initiative wus array is touched on the refusal path. Re-listing a claimed WU that is already a member is an idempotent no-op, so it is left untouched and does not block the rest of a batch. Changing membership mid-claim diverges the canonical spec from the claimed branch, and the divergence only surfaces at landing time, when wu:done refuses to complete the WU.

Three governed routes when a membership change is refused:

1. Set membership before the claim — wu:create --initiative <initiative-id>, or run the membership command while the WU is still ready.
2. End the claim, then repair — pnpm wu:done --id <wu-id> to land it, or pnpm wu:release --id <wu-id> to hand it back, then re-run the membership command.
3. If the claim is already diverged and wu:done is refusing it — pnpm wu:rebase --id <wu-id> replays the branch on the canonical spec.

Ready and unclaimed WUs link and unlink normally. Done WUs stay editable so governed legacy membership repair keeps working; a completed WU has no open claim to strand. There is no manual Git recovery path — hand-editing the spec is what causes the divergence in the first place.

Note

Known gap: pnpm initiative:bulk-assign --apply writes the same initiative field and is not behind this guard, so it can still change membership on a claimed WU. Run it against ready/unclaimed WUs only.

Running one

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

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

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

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

Artifact bundleplan.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@hellmai/lumenflow-control-plane-sdk — the shared contract powering local, cloud, and MCP surfaces.