Initiatives

Initiatives are multi-phase projects that coordinate multiple Work Units across lanes.

When to Use Initiatives

Use an initiative when:

• A feature spans multiple WUs (more than 3-4)
• Work spans multiple lanes (Framework + UI + Ops)
• There are dependencies between WUs
• You need phased rollout (Phase 1: Backend, Phase 2: Frontend, Phase 3: Launch)

Tip

If a task can be done in a single WU, don’t create an initiative. Initiatives add coordination overhead.

Creating an Initiative

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

This creates docs/04-operations/tasks/initiatives/INIT-001.yaml:

id: INIT-001
slug: user-authentication
title: User Authentication System
status: draft
priority: P1
owner: Team Alpha
target_date: '2026-02-01'

phases:
  - id: 1
    name: 'Phase 1: Backend'
    status: pending
  - id: 2
    name: 'Phase 2: Frontend'
    status: pending
  - id: 3
    name: 'Phase 3: Launch'
    status: pending

lanes:
  - 'Framework: Core'
  - 'Experience: UI'
  - 'Operations: Infrastructure'

wus: []

notes: ''

Initiative Lifecycle

draft → open → in_progress → done → archived

Status	Description
draft	Planning phase, defining scope
open	Approved, ready to start
in_progress	Active work underway
done	All phases complete
archived	Closed (cancelled or completed)

Adding WUs to an Initiative

Link a single WU

pnpm initiative:add-wu --initiative INIT-001 --wu WU-100

Bulk assign WUs

pnpm initiative:bulk-assign \
  --initiative INIT-001 \
  --wus WU-100,WU-101,WU-102 \
  --phase 1

Edit WU to add initiative

pnpm wu:edit --id WU-100 --initiative INIT-001 --phase 1

Phased Execution

Initiatives support wave-based execution where WUs in each phase are completed before moving to the next:

Phase 1: Backend
├── WU-100: Auth API (done)
├── WU-101: JWT tokens (done)
└── WU-102: Session store (in_progress)

Phase 2: Frontend (blocked by Phase 1)
├── WU-103: Login form
├── WU-104: Password reset
└── WU-105: Session UI

Phase 3: Launch (blocked by Phase 2)
├── WU-106: Deploy to production
└── WU-107: Monitoring setup

Viewing Initiative Status

pnpm initiative:status --id INIT-001

Output:

Initiative: User Authentication System
Status: in_progress
Progress: 33% (4/12 WUs done)

Phase 1: Backend [████████░░] 80%
  ✓ WU-100: Auth API (done)
  ✓ WU-101: JWT tokens (done)
  → WU-102: Session store (in_progress)

Phase 2: Frontend [░░░░░░░░░░] 0%
  ○ WU-103: Login form (ready)
  ○ WU-104: Password reset (ready)
  ○ WU-105: Session UI (ready)

Phase 3: Launch [░░░░░░░░░░] 0%
  ○ WU-106: Deploy to production (blocked)
  ○ WU-107: Monitoring setup (blocked)

Mermaid Visualization

pnpm initiative:status --id INIT-001 --format mermaid

Orchestrating Initiatives

For AI-assisted execution, use the orchestration commands:

Dry Run (Preview)

pnpm orchestrate:initiative --initiative INIT-001 --dry-run

Shows the execution plan without spawning agents. The output includes:

• Wave breakdown with WU assignments
• Bottleneck WUs (prioritize these for fastest unblocking)
• Recommended next steps with defaults

Tip

After dry-run, the output provides three options: 1. Checkpoint-per-wave (recommended): pnpm orchestrate:initiative -i INIT-001 -c - best for large initiatives 2. Full execution: pnpm orchestrate:initiative -i INIT-001 - best for small initiatives 3. Manual spawn: pnpm wu:spawn --id WU-XXX - best for testing individual WUs

Execute with Checkpoints

pnpm orchestrate:initiative --initiative INIT-001 --checkpoint-per-wave

This spawns agents for the current wave, then exits. Run again to process the next wave.

Continuous Execution

pnpm orchestrate:initiative --initiative INIT-001

Spawns agents for all ready WUs and polls for completion.

Monitor Progress

pnpm orchestrate:monitor --since 30m
pnpm mem:inbox --since 10m  # Check for coordination signals
pnpm orchestrate:init-status -i INIT-001  # Compact progress view

Shows signals from spawned agents. Use mem:inbox --since <duration> to check for coordination signals between waves.

Editing Initiatives

Update Status

pnpm initiative:edit --id INIT-001 --status in_progress

Add/Remove Lanes

pnpm initiative:edit --id INIT-001 --add-lane "Content: Documentation"
pnpm initiative:edit --id INIT-001 --remove-lane "Operations: Infrastructure"

Add Phases

pnpm initiative:edit --id INIT-001 --add-phase "Phase 4: Documentation"

Update Phase Status

pnpm initiative:edit --id INIT-001 --phase-id 1 --phase-status done

Block Initiative

pnpm initiative:edit --id INIT-001 \
  --blocked-by INIT-002 \
  --blocked-reason "Waiting for infrastructure"

Listing Initiatives

# List all
pnpm initiative:list

# Filter by status
pnpm initiative:list --status in_progress

# JSON output
pnpm initiative:list --format json

# Mermaid diagram
pnpm initiative:list --format mermaid

Linking Plans to Initiatives

Plans capture goals, scope, approach, and success criteria before implementation. Link a plan to an initiative to document the high-level strategy.

Create a New Plan

pnpm initiative:plan --initiative INIT-001 --create

This creates a plan template at docs/04-operations/plans/INIT-001-<slug>.md and links it to the initiative via the related_plan field.

Link an Existing Plan

pnpm initiative:plan --initiative INIT-001 --plan docs/04-operations/plans/my-plan.md

Plan URI Format

Plans are referenced using the lumenflow://plans/ URI scheme:

# In initiative YAML
related_plan: lumenflow://plans/INIT-001-user-authentication.md

Plan Template Structure

# INIT-001 Plan - User Authentication

## Goal

Primary objective of this initiative

## Scope

What is in scope and out of scope

## Approach

Key phases, milestones, and technical decisions

## Success Criteria

Measurable outcomes that define completion

## Risks

What could go wrong and mitigation strategies

## References

- Initiative: INIT-001
- Created: 2026-02-01

Tip

Create plans before breaking down into WUs. The plan helps identify phases and dependencies.

---

Best Practices

1. Keep initiatives focused

   An initiative should have a clear outcome. “Improve performance” is too vague; “Reduce API latency to under 100ms” is better.

2. Limit phases to 3-5

   More phases create coordination overhead. If you need more, consider splitting into multiple initiatives.

3. Define dependencies upfront

   Before starting, map out which WUs block which. This prevents surprises mid-execution.

4. Use checkpointing for AI agents

   The --checkpoint-per-wave flag prevents context exhaustion when orchestrating large initiatives.

5. Review progress regularly

   Run initiative:status at least daily to catch blockers early.

CLI Reference

Command	Description
pnpm initiative:create	Create new initiative
pnpm initiative:edit	Edit initiative YAML
pnpm initiative:list	List all initiatives
pnpm initiative:status	Detailed status view
pnpm initiative:add-wu	Link WU to initiative
pnpm initiative:bulk-assign	Bulk assign WUs
pnpm orchestrate:initiative	Orchestrate execution
pnpm orchestrate:init-status	Compact status view
pnpm orchestrate:monitor	Monitor agent progress

Next Steps

• Flow Metrics – Track delivery performance
• AI Agents – Agent orchestration
• Work Units – WU fundamentals