Why LumenFlow?

AI agents are getting remarkably capable. They read your codebase, write production code, call APIs, deploy services, and manage infrastructure. That’s the good news.

The bad news? Nobody is governing them. There’s no audit trail, no enforceable policy, and no scope boundary that an agent can’t accidentally wander past. When something goes wrong — and it will — you have no proof of what happened and no mechanism to prevent it next time.

LumenFlow changes this. It inserts a governance kernel that scope-checks, policy-checks, and receipts every tool call dispatched through it, before that call runs.

The Problem

Today’s AI agent workflows rely on one of three approaches. All three break down as you scale.

Hope-based governance

Agents run with full access. You hope they follow instructions. There’s no audit trail, no rollback, and no proof of what happened when things go sideways.

Prompt or plugin-based trust

Methodology prompts, agent frameworks, and skill plugins distribute useful working practices. But guidance is not a wall — agents can ignore it when they hallucinate, over-optimize, or take tool actions outside the intended workflow.

After-the-fact enforcement

GitHub Actions and CI pipelines catch problems after they’ve already happened. By the time a check fails, the agent has written files, made commits, and potentially pushed to production. LumenFlow prevents this by enforcing policy before the tool call executes — not in CI minutes later, after the damage is done.

The common thread? None of these provide real-time governance — enforcement that happens before each action, not after the damage is done.

Four Kernel Guarantees

LumenFlow’s kernel provides four guarantees for every tool call it dispatches:

1. Scope Intersection

Every kernel-dispatched tool call is checked against a 4-level permission model. Workspace, lane, task, and tool scopes must all agree before anything happens. One “no” at any level and the call is blocked.

The block below is illustrative. It shows the check order; it is not CLI output, and no code prints these lines.

Agent requests: file:write("src/auth/login.ts")
  ✓ Workspace scope: src/** allowed
  ✓ Lane scope: src/auth/** allowed (Framework: Core lane)
  ✓ Task scope: src/auth/** allowed (WU code_paths)
  ✓ Tool scope: file:write allowed
  → PERMITTED

2. Deny-Wins Policies

Policies are evaluated in a layered cascade where strictness only goes one direction — up.

• A workspace policy that denies .env access can’t be overridden by a task
• A lane policy that blocks git push --force applies to every agent in that lane
• Pack policies (like quality gates) are enforced by the kernel, not left to the agent’s discretion

Think of it as the principle of least privilege, enforced structurally rather than by convention.

3. Evidence Receipts

Every kernel-dispatched tool call produces an append-only, content-addressed audit record — what was requested, what scopes were checked, what policies were evaluated, and what the outcome was. This happens whether the action succeeds or fails.

This isn’t logging. It’s a tamper-evident record — content-addressed with unkeyed SHA-256 — that detects accidental change, independently of what any agent reports. There is no signing key: it cannot prove a record was never rewritten by a process that already had write access to it.

4. Kernel-Confined Tool Dispatch

LumenFlow’s own kernel tool dispatch — the pack subprocess tools it runs on your behalf — executes inside a bwrap sandbox with write confinement and deny overlays on secrets, enforced by the Linux kernel. That’s what LumenFlow confines today, and only on Linux. The kernel’s subprocess dispatch needs bwrap, so on macOS and Windows it refuses to run. The macOS sandbox-exec engine and the Windows AppContainer engine serve the operator layer, not kernel dispatch.

The coding-agent session itself — the CLI, IDE agent, or desktop agent a developer starts — runs with the developer’s own authority, unless it is started in an opt-in LumenFlow box (Linux only, wu-sandbox --box). On Linux, a repository can require boxed sessions through a host-config floor, and mutating lifecycle commands run outside a box are then refused. Otherwise, enable your agent host’s own sandbox. See Agent safety for the full picture, including the opt-in wu:sandbox confinement available for governed lifecycle commands: on Linux it is a real bwrap sandbox with a read-only system and toolchain set and a read-write worktree and state set, not merely write confinement.

How It Compares

Aspect	No Governance	Prompt/Plugin Methodology	CI-Only (GitHub Actions)	LumenFlow
Governance	None	Role and workflow guidance	Post-hoc checks	4-level scope, deny-wins
Evidence	None	Conversation logs	CI logs	Tamper-evident receipts
Isolation	None	None	Container-level	Kernel tool dispatch, Linux only
Policy	None	Prompt suggestions	Pipeline rules	Real-time deny-wins cascade
Extensibility	N/A	Skills and tool bundles	Marketplace actions	Pack system with scoped policies

Domain Packs

The kernel is domain-agnostic on purpose. It doesn’t know about software delivery, infrastructure provisioning, or compliance auditing. Domain knowledge comes from packs — pluggable extensions that teach the kernel how to work in your world.

Software Delivery Pack

Ships built-in. Work Units, lanes, gates, worktrees, memory, and 100+ CLI commands. This is what we use to build LumenFlow itself — we eat our own cooking.

Explore the Pack →

Build Your Own

Customer support, data pipelines, infrastructure provisioning, compliance auditing — if you can define the rules, you can build a pack.

Create a Pack →

Tip

Most teams start with the Software Delivery Pack, which ships built-in. If you’re a software team, get started here — everything works out of the box.

When You Need LumenFlow

It’s essential when:

• AI agents touch your codebase, infrastructure, or production services
• You need an audit trail of what agents did and why
• Policy enforcement must be real — not just “please don’t”
• You need to prove compliance to regulators, customers, or your future self
• Multiple agents work in parallel and need coordination boundaries

You might not need it when:

• You only use AI for chat-based Q&A with no tool access
• Agents operate in fully disposable, throwaway environments
• Your existing CI/CD pipeline gives you enough governance for your risk tolerance

Philosophy

Four principles guide everything we build:

1. Policy as code — Governance rules are declarative configurations, not verbal agreements or wiki pages
2. Evidence over claims — Append-only receipts prove what happened. Status updates and ticket comments don’t.
3. Continuous governance — Every kernel-dispatched action is governed in real-time, not reviewed after the sprint ends
4. Agents as governed participants — Agents get the same accountability mechanisms as humans. First-class team members, first-class oversight.

Getting Started

For Humans

Step-by-step setup guide for developers.

Get Started →

For AI Agents

Canonical onboarding for AI coding assistants.

Agent Quickstart →

Keep reading:

• What is LumenFlow? — Architecture overview
• Kernel Runtime — How the kernel dispatches and governs tool calls
• Packs — The extension mechanism for domain-specific tooling
• Licensing — Per-package licensing status