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?

Small enough to complete in a single session (2-4 hours for humans, faster for AI). If a WU takes longer, split it.

Rule of thumb:

1-3 acceptance criteria
Touches 1-2 code paths
Has clear, testable outcomes

Can multiple people work on the same WU?

No. WIP=1 per lane means one WU per lane at a time. If you need parallel work, use multiple lanes or split the WU.

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

If the bug is in your code_paths and small (under 10 lines), fix it in place. Otherwise, create a new WU for the bug and finish your current work first.

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, define them in workspace.yaml:

lanes:
  definitions:
    - name: 'Framework: Payments'
      code_paths: ['src/payments/**']
    - name: 'Experience: Mobile'
      code_paths: ['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 for pre-existing failures with proper documentation. Normally, gates run via wu:prep in the worktree:

pnpm wu:done --id WU-042 --skip-gates \
  --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?

The CLI provides the full LumenFlow experience (worktrees, gates, memory). Without it, you can still use LumenFlow with manual WU YAML management.

What Node.js version do I need?

Node.js 22 or higher (LTS recommended).

Does the CLI work with npm?

Yes. We recommend pnpm, but npm works too:

npm install -D @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"

AI Agents

Which AI tools work with LumenFlow?

Any AI coding assistant that can:

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

Popular options: Claude Code, Cursor, GitHub Copilot, Aider, Continue.

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 --client <client>
# ... 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 Cursor Rules or system prompts?

Cursor Rules, .cursor/rules.txt, Claude’s CLAUDE.md, and system prompts guide an agent inside a single editor or vendor. They’re instructions the agent is asked to follow.

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