FAQ

General

What is LumenFlow?

LumenFlow is the control plane for AI software delivery. It enforces policy, approvals, and evidence for agent work with a governance kernel and runtime. Like an OS kernel mediates between programs and hardware, LumenFlow mediates between agents and everything they touch — filesystem, git, APIs, databases, cloud services.

Is LumenFlow a project management tool?

No. LumenFlow is an agent governance kernel with pluggable domain packs. The first-party pack set currently includes Software Delivery for governed delivery workflows, Sidekick for workspace-local productivity, and Agent Runtime for governed model turns. You can build packs for any domain.

Do I need AI agents to use LumenFlow?

LumenFlow is designed for AI agents, but the Software Delivery Pack works for human-only teams too. The workflow (WUs, gates, lanes) benefits any team that wants faster feedback and evidence-based completion.

How do I get access to LumenFlow?

LumenFlow is private commercial software. Access to packages and infrastructure is granted by arrangement. Contact licensing@lumenflow.dev for licensing and access. See Licensing & Access for details.

Work Units (WUs)

What’s the difference between a WU and a ticket?

A WU is an executable specification. It includes:

Acceptance criteria that define “done”
Code paths that scope what can be changed
Test paths for verification

A ticket is typically just a description. A WU is a contract.

How big should a WU be?

One coherent, independently shippable outcome should be one WU. Complexity selects an execution strategy: use single-session for small work, checkpoint-resume for medium or long-running work, and orchestration when an atomic outcome is complex. Split only when the parts can ship, review, and roll back independently.

Can multiple people work on the same WU?

One WU has one active owner. Lane WIP limits are configurable, and code-path overlap checks prevent unsafe concurrent claims. Parallelize independent WUs across lanes or across disjoint paths in a lane whose configured WIP limit permits it.

What if I find a bug while working on a WU?

If the bug is in your code_paths and part of the same acceptance outcome, fix it in place. For an unrelated discovery, capture it with pnpm mem:create --type discovery --wu WU-XXX; do not widen the active WU or create untriaged work from inside a worker session.

Lanes

What are lanes?

Lanes are parallel tracks for different domains of work. Examples:

Framework: Core - Core business logic
Experience: UI - User interface
Operations: Infrastructure - DevOps and CI/CD

Each lane can have one WU in progress at a time (WIP=1).

How do I choose lane names?

Use the Parent: Sublane format. The parent and sublane should each start with a capital letter, and the sublane can include / when you need a hierarchical name such as Framework: CLI/Commands or Content: Framework/Docs.

Common parents:

Framework (code packages)
Experience (UI/UX)
Operations (infrastructure, CI/CD)
Content (documentation, marketing)

Examples:

Framework: Core
Operations: Infrastructure
Content: Framework Docs

Can I have custom lanes?

Yes. Use the lane lifecycle commands so the kernel and Software Delivery representations stay in sync:

pnpm lane:create --name "Framework: Payments" --add-path "src/payments/**"
pnpm lane:create --name "Experience: Mobile" --add-path "apps/mobile/**"

Gates

What are gates?

Gates are automated quality checks that run before a WU can be completed:

Format check (Prettier, gofmt)
Lint check (ESLint, ruff)
Type check (TypeScript, mypy)
Tests (Vitest, pytest)

Can I skip gates?

Only explicitly named skippable gates can be skipped, and only with matching structured evidence that the same failure exists on main:

pnpm wu:done --id WU-042 --skip-gate lane-health \
  --reason "Pre-existing lint failure" \
  --fix-wu WU-050

Never skip gates for failures introduced by your own work.

Do gates replace code review?

For most changes, yes. Gates provide faster, more consistent feedback than human review. For critical changes (auth, payments, PII), use escalation triggers to require human approval.

Worktrees

What is a worktree?

A Git worktree is a separate working directory linked to the same repository. LumenFlow creates a worktree for each WU, isolating your work from other changes.

Why use worktrees instead of branches?

Worktrees provide true isolation:

Your in-progress changes don’t affect others
You can switch WUs without stashing
Multiple WUs can run in parallel (one per lane)

What happens to my worktree when I finish?

pnpm wu:prep and pnpm wu:done together:

wu:prep runs gates in the worktree
wu:done merges to main (fast-forward)
wu:done creates the stamp
wu:done deletes the worktree

CLI

Do I need to install the CLI?

Yes. The CLI is the supported lifecycle surface for worktrees, gates, WU state, and memory. Do not manage WU YAML or workspace.yaml by hand.

What Node.js version do I need?

Node.js 26.0.0 or higher. LumenFlow recommends Node.js 26.8.1, the current stable release.

Does the CLI work with npm?

Yes. We recommend pnpm, but npm works too:

npm install -D @hellmai/lumenflow-cli
npx wu-create --title "Update README" --lane "Operations: Documentation" \
  --type documentation --exposure documentation \
  --description "Clarify setup steps" \
  --acceptance "README includes updated setup instructions" \
  --notes "Documentation-only correction; verify the rendered command"

AI Agents

Which AI tools work with LumenFlow?

Any AI coding assistant that can:

Read files (WU specs, code)
Write code
Run commands

LumenFlow intentionally does not maintain a per-host support matrix. Configure your chosen host to read LUMENFLOW.md and then LUMENFLOW.local.md when it exists.

How do AI agents know what to do?

They read the WU spec:

acceptance:
  - Users can log in with email/password
  - JWT tokens issued with 1-hour expiry
code_paths:
  - src/auth/

The spec tells them what to build and where to put it.

Can AI agents run wu:done?

Yes. AI agents can run the full workflow:

pnpm wu:claim --id WU-042 --lane "Framework: Core"
cd worktrees/framework-core-wu-042
pnpm wu:brief --id WU-042
# ... implement ...
pnpm wu:prep --id WU-042
cd /path/to/repo
pnpm wu:done --id WU-042

Troubleshooting

See Troubleshooting Guide

Common issues:

Gate failures
WU state issues
Worktree problems
Git conflicts

Is LumenFlow right for me?

How is this different from agent-host instructions or system prompts?

Agent-host instruction files and system prompts guide an agent inside one execution environment. They are project-owned discovery and invocation mechanisms, not LumenFlow-managed policy surfaces.

LumenFlow is governance, not guidance. It enforces policy at the OS level for any agent, any tool, any workflow — before the tool call executes, not as a suggestion the model can hallucinate away from. If an agent tries to write .env, the Linux kernel stops the write; it doesn’t matter whether the agent “understood” the rule.

What’s the operational cost?

Minimal. The kernel adds a small per-tool-call overhead for scope and policy evaluation. Worktrees use git and the filesystem you already have. The CLI is a local binary. Zero cloud dependency unless you opt into a hosted control plane.

Can I migrate away if I don’t like it?

Yes. WU specs are YAML. Stamps are immutable files on disk. Evidence records are append-only JSONL. All configuration is declared in workspace.yaml. You own every file — export them, stop running the CLI, and you’re out. No proprietary lock-in on your state.

FAQ