Existing Projects

LumenFlow is a Node-distributed governance CLI, but the repository it governs can use any language or framework. Existing source layout, package manager, ticket system, and CI can remain in place.

Prerequisites

• a Git repository;
• Node.js 26.0.0 or newer for the CLI (Node.js 26.8.1 Current recommended);
• pnpm 11.4.0 or newer (12.3.4 Current recommended) or npm 12.0.2 or newer;
• access to the private LumenFlow package channel.

Install and merge

1. Confirm the clone has an attributable local Git identity.

   git config --local user.name
   git config --local user.email

   If either value is empty, the developer sets it for this clone:

   git config --local user.name "Your Name"
   git config --local user.email "you@example.com"

2. Install the CLI locally.

   pnpm add -D @hellmai/lumenflow-cli

3. Merge the LumenFlow scaffold into the existing repository.

   pnpm lumenflow --merge

   The command preserves project-owned tool instructions and host hooks. It creates or updates the LumenFlow-owned contract and managed workspace surfaces.

   A project-owned tool file (for example CLAUDE.md) retained from an older LumenFlow release may still carry a directive telling an agent to edit a now-managed file. pnpm lumenflow:doctor and pnpm lumenflow:upgrade detect that specific line and print a non-gating advisory naming the file, the exact line, and the remedy: move project-owned rules into LUMENFLOW.local.md, then replace the file body with a pointer to LUMENFLOW.md and LUMENFLOW.local.md. LumenFlow never edits the file itself.

   On a later pnpm lumenflow:upgrade, the CLI also reconciles its managed ignore rules and stops tracking runtime telemetry under the legacy .lumenflow/telemetry path or the .lumenflow/state/packs/software-delivery/telemetry namespace. Existing telemetry files stay in the working tree, and new writes are ignored. Lifecycle evidence such as WU events, migration state, completion stamps and the lifecycle-enforcement manifest remains tracked.

4. Verify the installation and discover the current commands.

   pnpm lumenflow:doctor
   pnpm lumenflow:commands
   pnpm wu:create --help

   Running --help before first use is audited safe only for commands listed by pnpm lumenflow:commands. It does not extend to project-authored scripts: read an unfamiliar script or ask its author before assuming a flag is a no-op, especially one that can deploy, authenticate, or contact an external service.

   Doctor may also report a verified Turbo/pnpm compatibility warning when the consumer has a valid multi-document pnpm lockfile and a consumer-local Turbo version older than stable 2.9.7. Upgrade the consumer-owned direct turbo dependency to stable 2.9.7 or newer with the project’s package manager, then commit the manifest and lockfile changes through the normal workflow. Missing or ambiguous local evidence is reported as unknown. The compatibility issue may make wu:prep fall back to a full typecheck; any extra time depends on the project workload and has not been measured by this diagnostic.

5. Complete lane lifecycle once before the first delivery WU.

   pnpm lane:setup
   pnpm lane:validate
   pnpm lane:lock

The generated structure includes:

• workspace.yaml - LUMENFLOW.md - LUMENFLOW.local.md (optional, project-owned additions) - .lumenflow/ - constraints.md - skills/ - docs/tasks/ (default) or docs/operations/tasks/ (arc42)

Do not build a manual parallel installation

Non-Node projects still use the local Node CLI. Do not hand-create workspace.yaml, WU YAML, backlog views, stamp directories, or Git hooks. Those files have schema, namespace, and lifecycle behavior that the CLI keeps consistent across upgrades.

Map your repository to lanes

Use lane commands rather than editing either lane representation in workspace.yaml:

pnpm lane:create \
  --name "Framework: Core" \
  --wip-limit 1 \
  --add-path "src/**"

pnpm lane:create \
  --name "Content: Documentation" \
  --wip-limit 2 \
  --add-path "docs/**"

pnpm lane:list --json

Top-level kernel lanes and software_delivery.lanes.definitions are related but distinct. The lane lifecycle synchronizes them and keeps scope permissions aligned with delivery code paths.

Map your quality commands

Initialization auto-detects dotnet, java, go, rust, and python presets from repository markers (*.csproj/*.sln, pom.xml/build.gradle, go.mod, Cargo.toml, pyproject.toml/requirements.txt/setup.py). ruby, php, and node are real presets too, but none has a marker rule yet — any project whose markers don’t match one of the five above (including a genuine Ruby, PHP, or unrecognized-ecosystem repo) silently falls back to the node preset. Pass an explicit --preset whenever detection is wrong or your ecosystem isn’t in the detected five:

pnpm lumenflow --merge --preset python

Use fully qualified config keys for supported overrides:

pnpm config:set --key software_delivery.gates.execution.preset --value python
pnpm config:set --key software_delivery.gates.minCoverage --value 90
pnpm config:get --key software_delivery.gates

Run pnpm config:set --help before changing a key and use the generated Configuration Reference for the current schema.

Create a verification WU

This documentation-only WU proves the lifecycle without requiring a fake source change:

Run wu:brief immediately after wu:claim

Run wu:brief immediately after wu:claim, before any implementation. Evidence is bound to the claim, so a brief rendered before the claim exists mints no usable evidence.

pnpm wu:create \
  --title "Verify LumenFlow onboarding" \
  --lane "Content: Documentation" \
  --type documentation \
  --exposure documentation \
  --description "Verify the installed CLI can execute a complete governed documentation lifecycle" \
  --acceptance "A small onboarding note is claimed, prepped, completed, and verified" \
  --notes "Use an existing documentation file and remove the temporary wording before completion"

# Use the generated ID printed by wu:create.
pnpm wu:claim --id <wu-id> --lane "Content: Documentation"
pnpm wu:brief --id <wu-id>
cd worktrees/content-documentation-<wu-id>

# Make and commit the scoped documentation change here.
pnpm wu:prep --id <wu-id>

cd /path/to/main
pnpm wu:done --id <wu-id>
pnpm wu:verify --id <wu-id>

Developer access and project-owned hooks

Git hosting permissions decide who may clone and push. LumenFlow requires a non-empty Git name and email for attribution, but its generated surfaces do not pin a person, organization domain, or GitHub account. If an existing repository hook compares developers against a personal allowlist, that is project-owned access policy: remove it or move the machine-specific safeguard into local Git configuration before onboarding another developer.

Worktrees share the clone’s local Git configuration through the common Git directory, so a valid per-clone identity applies to every claimed WU.

Gradual adoption

1. Start with new work; do not bulk-convert every old ticket.
2. Keep the external roadmap and link structured external work items when needed.
3. Run pnpm gates in CI alongside existing checks.
4. Upgrade with pnpm lumenflow:upgrade --latest; do not copy files from a newer repository.

Next steps

• Manual Quickstart — first governed WU
• Language Guides — preset-specific commands
• Team Workflow — lanes and handoffs
• Troubleshooting — recovery paths