Upgrading LumenFlow

This guide covers how to upgrade your LumenFlow installation to the latest version.

Quick Upgrade (Recommended)

The fastest way to upgrade all LumenFlow packages is with the built-in upgrade command.

pnpm lumenflow:upgrade --latest

This command:

• Updates all 7 @lumenflow/* packages atomically
• Uses micro-worktree isolation (no WU needed)
• Updates both package.json and pnpm-lock.yaml
• Works from your main checkout

Tip

The upgrade command handles version coordination automatically. All packages (except @lumenflow/metrics) are versioned together for compatibility.

Manual Upgrade

If you prefer manual control or encounter issues with the upgrade command, you can update packages directly.

pnpm

pnpm up @lumenflow/core @lumenflow/cli @lumenflow/memory \
  @lumenflow/agent @lumenflow/initiatives @lumenflow/shims \
  @lumenflow/metrics --latest

npm

npm update @lumenflow/core @lumenflow/cli @lumenflow/memory \
  @lumenflow/agent @lumenflow/initiatives @lumenflow/shims \
  @lumenflow/metrics

Post-Upgrade Steps

After upgrading, sync your agent documentation to get the latest skills and guidance.

1. Sync agent documentation

   pnpm exec lumenflow docs:sync --force

   This updates:

   • .lumenflow/agents/ — Vendor-agnostic agent guidance
   • .claude/skills/ — Claude Code skills (if present)
   • LUMENFLOW.md — Workflow entry point

2. Verify the upgrade

   pnpm list @lumenflow/cli

3. Check for config changes

   Review the Changelog for any breaking changes that may require config updates.

Upgrading to v2.3.2

Current

Version 2.3.2 is the current tooling version in this repo. See the Changelog for details and migration notes.

Upgrade Steps

# 1. Upgrade packages
pnpm add -D @lumenflow/cli@latest

# 2. Sync documentation
npx lumenflow-docs-sync --force

# 3. Verify
pnpm list @lumenflow/cli  # Should show latest version

Upgrading from v1.x to v2.x

If you’re upgrading from v1.x, see the Migration Guide for breaking changes and required configuration updates.

Key changes in v2.0:

• Config version changed to version: '2.0'
• Lane format now requires “Parent: Sublane” (e.g., Framework: Core)
• State directory is .lumenflow/

Version Compatibility

All @lumenflow/* packages (except metrics) should be at the same version for best compatibility.

Package	Current
@lumenflow/core	2.3.2
@lumenflow/cli	2.3.2
@lumenflow/memory	2.3.2
@lumenflow/agent	2.3.2
@lumenflow/initiatives	2.3.2
@lumenflow/shims	2.3.2
@lumenflow/metrics	2.3.2

See the Compatibility Matrix for full version details.

Troubleshooting

Upgrade command not found

If pnpm lumenflow:upgrade is not recognized, ensure you have @lumenflow/cli installed:

pnpm add -D @lumenflow/cli

Package version mismatch

If you see version mismatch warnings, run the upgrade command again:

pnpm lumenflow:upgrade --latest

docs:sync fails

If docs:sync --force fails, ensure the CLI is built:

pnpm build --filter @lumenflow/cli
pnpm exec lumenflow docs:sync --force

Next Steps

• Changelog — See what’s new in each version
• Compatibility Matrix — Version requirements
• Migration Guide — Upgrading from v1.x