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 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.

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 since WU-3918 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; that is recorded as a follow-up.

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 INIT-001, or run the membership command while the WU is still ready.
2. End the claim, then repair — pnpm wu:done --id WU-XXXX to land it, or pnpm wu:release --id WU-XXXX 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-XXXX 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 yet behind this guard, so it can still change membership on a claimed WU. Run it against ready/unclaimed WUs only until the follow-up lands.

Initiative admission port (internal, not enabled)

An internal, default-disabled InitiativeAdmissionPort now exists inside the Software Delivery pack. It is not how WUs are created today: no command, MCP tool, cloud route or manifest default selects it, and the sections above remain the current way to create and link work. It is documented here so the contract is public before anything switches over.

The port declares five members — prepare, apply, findReceipt, repairProjection and auditLegacy. Only prepare is implemented; the three mutating members and the receipt lookup refuse with the stable error class ADMISSION_NOT_IMPLEMENTED rather than pretending to work.

prepare turns one or more captured seeds into a plan, and it is a pure read:

• It writes nothing — not the repository, memory store, initiatives, phases, allocators, lane locks or WIP state, authority lease, approval store, or the lifecycle event stream.
• It allocates no WU and no initiative ID. Candidates are addressed by a content-addressed candidate_key, which is a plan-local correlation key rather than an identity.
• It produces complete N-to-M coverage: several seeds may compose into one candidate, and one seed may split across several candidates only when each part is independently shippable. Seed-to-candidate and candidate-to-seed edges must be exact reciprocals, with no orphan on either side.
• It derives one deterministic dependency order. Candidate keys are derived from dependency leaves toward dependents, and the recorded order is the Kahn traversal with simultaneously ready candidates broken by candidate key, so re-ordering the inputs produces a byte-identical plan and a cycle is refused.
• It refuses a seed whose life already ended unless its latest resolution reopened it, and it validates lane fit, paths, tests, sizing, dependencies, exposure, the five-surface documentation matrix, and a capability-neutral routing recommendation.

Semantic similarity is advisory only: it ranks review suggestions beside the plan, never inside it, and cannot add or remove a dependency edge or decide a seed’s disposition.

Membership still behaves exactly as described above — this port changes nothing about wu:create --initiative, initiative:add-wu, or the WU-3918 rule that a claimed WU’s membership is immutable.

Note

Status: internal and default-disabled. Treat the admission port as planned behaviour, not as an available workflow, until the release notes say the cutover has happened.

Cloud and Desktop admission adapters (internal, not enabled)

WU-4004 (INIT-120 P4B/P4C) adds structurally compatible Cloud HTTP and Desktop CLI adapters for the admission port above, under @hellmai/lumenflow-surfaces. Like the port itself, this is planned behaviour, not an available workflow:

• No HTTP route, CLI command, or manifest default constructs a bound adapter. A request against the running Cloud or Desktop surface today still takes the unchanged legacy creation path.
• The Cloud adapter refuses an unauthenticated or same-user-only caller before any write; independent authenticated principals and the server-side lease/fence checks it delegates to are Cloud-only requirements (plan section 7).
• The Desktop adapter calls only through a typed local-or-remote transport; no UI action built on it can write a discovery or WU file directly.
• Both surfaces’ public seed alias returns SEED_ALIAS_NOT_CUTOVER and stays absent from generated capability listings until the central activation record commits.

Note

Status: internal and default-disabled. See the repository’s internal architecture notes (docs/05-building-block-view/cloud-desktop-admission-adapters.md, marked internal) for the full contract.

CLI creation, repair, closeout, and wakeup bindings (internal, not enabled)

WU-3999 (INIT-120 P4D-CLI) binds wu:create, wu:repair/doctor, wu:closeout, and wu:wakeup to the shared admission vocabulary above, all of it planned behaviour, not an available workflow:

• wu:create still runs only the existing direct-creation flow; no invocation consumes a real admission plan yet.
• doctor --repair --dry-run previews a repair with a status: "not_activated" payload and exits non-zero, the same pre-activation convention wu:closeout and wu:wakeup use below; wu:repair is unchanged and declares no binding of its own. doctor refuses --repair/--dry-run supplied alone rather than running an ordinary diagnostic silently.
• wu:closeout and wu:wakeup are prepared CLI modules that print the same status: "not_activated" preview and exit non-zero. Neither ships a bin entry, a PUBLIC_MANIFEST entry, or a published-help listing.

Note

Status: internal and default-disabled. See the repository’s internal architecture notes (docs/05-building-block-view/closeout-blocker-and-deferred-wakeup.md, marked internal) for the full contract.

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.