Compatibility Matrix

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

Package Versions

All @lumenflow/* packages are versioned together — the current published stable for every package is v6.0.6. 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 | | ----------------------- | ---------- | ------- | ---------------------------- | | 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 v6.0.6 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 |