Compatibility Matrix

This matrix shows compatibility between LumenFlow package versions, runtime requirements, and supported tools. Current published stable: v5.3.2.

Package Versions

All @lumenflow/* packages are versioned together — the current published stable for every package is v5.3.2. Use matching versions for best compatibility.

Package	Minimum	Notes
@lumenflow/core	4.0.0	Core WU lifecycle
@lumenflow/cli	4.0.0	Command-line interface
@lumenflow/kernel	4.0.0	Runtime primitives
@lumenflow/runtime	4.0.0	Daemon, scheduler
@lumenflow/packs	4.0.0	Pack framework
@lumenflow/mcp	4.0.0	MCP server
@lumenflow/memory	4.0.0	Session tracking
@lumenflow/agent	4.0.0	Agent definitions
@lumenflow/initiatives	4.0.0	Multi-phase projects
@lumenflow/metrics	4.0.0	DORA metrics and flow
@lumenflow/shims	4.0.0	Safety wrappers
@lumenflow/control-plane-sdk	4.0.0	Control plane SDK

Tip

Run pnpm lumenflow:upgrade --latest to update all packages to the latest compatible versions.

Runtime Requirements

Node.js

LumenFlow Version	Node.js Minimum	Node.js Recommended	Notes
4.x	22.0.0	22.x	ES modules, native fetch
3.x	22.0.0	22.x	ES modules, native fetch
2.x	20.0.0	22.x	ES modules, native fetch
1.x	18.0.0	20.x	CommonJS fallback available

Package Managers

Package Manager	Minimum Version	Recommended	Notes
pnpm	9.0.0	10.x	Primary support
npm	10.0.0	Latest	Supported
yarn	4.0.0	Latest	Berry (v4) only
bun	1.0.0	Latest	Experimental

Caution

pnpm is the primary supported package manager. Some features may have degraded functionality with npm or yarn.

Config Version Compatibility

Config Version	LumenFlow Version	Breaking Changes
version: '2.0'	2.0.0+	Lane format, stamp location
version: '1.0'	1.0.0 - 1.6.x	Original format

Config Migration

# Old (v1.0)
lanes:
  - name: Core
    wip: 1

# New (v2.0)
lanes:
  definitions:
    - name: 'Framework: Core'
      wip_limit: 1

Gate Presets

Node Preset

Tool	Version	Gate Step
Prettier	3.x	format
ESLint	9.x (flat config)	lint
TypeScript	5.7+	typecheck
Vitest	4.x	test

Python Preset

Tool	Version	Gate Step
Ruff	0.8+	format, lint
mypy	1.x	typecheck
pytest	8.x	test

Go Preset

Tool	Version	Gate Step
gofmt	Go 1.21+	format
golangci-lint	1.60+	lint
go vet	Go 1.21+	typecheck
go test	Go 1.21+	test

Rust Preset

Tool	Version	Gate Step
rustfmt	Latest	format
clippy	Latest	lint
cargo check	Rust 1.75+	typecheck
cargo test	Rust 1.75+	test

Java Preset

Tool	Version	Gate Step
google-java-format	1.23+	format
SpotBugs	4.8+	lint
javac	Java 17+	typecheck
JUnit/Maven	5.x / 3.9+	test

Ruby Preset

Tool	Version	Gate Step
RuboCop	1.68+	format, lint
Sorbet	0.5+	typecheck
RSpec	3.13+	test

PHP Preset

Tool	Version	Gate Step
PHP-CS-Fixer	3.x	format
PHPStan	2.x	lint
Psalm	6.x	typecheck
PHPUnit	11.x	test

.NET Preset

Tool	Version	Gate Step
dotnet format	.NET 8+	format
dotnet build	.NET 8+	typecheck
dotnet test	.NET 8+	test

GitHub Action Compatibility

Action Version	LumenFlow Version	GitHub Runner
v1.x	2.0.0+	ubuntu-latest, macos-latest

Action Input Compatibility

Input	Type	Available Since
preset	string	v1.0.0
format	string	v1.0.0
lint	string	v1.0.0
typecheck	string	v1.0.0
test	string	v1.0.0
config-path	string	v1.0.0

AI Agent Compatibility

Claude Code

Feature	Minimum Version	Notes
Skills loading	Any	Via /skill command
MCP tools	Claude Code 0.2.x+	For tool integration

Other Agents

Agent	Compatibility	Notes
Cursor	Full	Uses .cursor/ config
Aider	Full	Uses .aider.conf.yml
Continue	Partial	Basic workflow support
GitHub Copilot	Partial	No memory integration

Editor Integration

Editor	Integration	Config Location
VS Code	Tasks, settings	.vscode/
Cursor	Rules, settings	.cursor/
Neovim	Config	lua/ (custom)
JetBrains	Run configs	.idea/ (custom)

Operating System Support

OS	Support Level	Notes
Linux	Full	Primary development platform
macOS	Full	Tested on Apple Silicon and Intel
Windows	Partial	WSL2 recommended
Windows (native)	Limited	Path handling may have issues

Note

Windows native support is improving. For best results, use WSL2 or Git Bash.

Deprecation Timeline

Feature	Deprecated	Removed	Migration
isAgentBranchSync()	v2.0.0	v3.0.0	Use async isAgentBranch()
Single-word lanes	v2.0.0	v3.0.0	Use “Parent: Sublane” format
wu:complete command	v1.5.0	v2.0.0	Use wu:done
Config version: '1.0'	v2.0.0	v3.0.0	Update to version: '2.0'

Upgrade Path

From v3.x to v4.0

1. Run pnpm lumenflow:upgrade --latest to update all @lumenflow/* packages to the current v5.3.2 line.
2. Review the Changelog for any breaking changes since your current version — the changelog is generated from git history and covers every merged Work Unit per release.
3. Re-run pnpm lumenflow:doctor to verify the upgrade.

From v2.x to v3.0

1. Update all package versions to 3.0.0
2. Install new packages: @lumenflow/kernel, @lumenflow/runtime, @lumenflow/packs, @lumenflow/mcp, @lumenflow/control-plane-sdk
3. Create workspace.yaml for kernel configuration (see Workspace Spec)
4. Update lane definitions to granular format (e.g., Framework: Core → Framework: Core Lifecycle)
5. Remove any remaining single-word lanes or isAgentBranchSync() usage

Checking Compatibility

# Check current version
pnpm list @lumenflow/cli

# Validate config compatibility
npx lumenflow-validate

# Check for updates
pnpm outdated @lumenflow/*

Support Matrix

Version	Status	Security Fixes	Bug Fixes
4.x	Active	Yes	Yes
3.x	Maintenance	Yes	Critical only
2.x	EOL	No	No
1.x	EOL	No	No