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.

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 consult its owner before assuming a flag is a no-op, especially one that can deploy, authenticate, or contact an external service.

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 node, python, go, rust, dotnet, java, ruby, and php presets from repository markers. Select an explicit preset only when detection is wrong:

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-123 --lane "Content: Documentation"
pnpm wu:brief --id WU-123
cd worktrees/content-documentation-wu-123

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

cd /path/to/main
pnpm wu:done --id WU-123
pnpm wu:verify --id WU-123

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