AI Agent Integration

LumenFlow treats AI agents as first-class collaborators. This guide covers how to work effectively with AI assistants.

Works with Any AI

LumenFlow is friction-free for any AI coding assistant. If your AI can read project files, it can use LumenFlow—just point it at AGENTS.md and LUMENFLOW.md. No vendor lock-in, no special setup required.

Enhanced integrations for Claude Code, Cursor, Windsurf, and Cline provide deeper features but are entirely optional.

Model-Agnostic Lifecycle Authority

LumenFlow does not key lifecycle decisions off a provider, model, client, hosted runner, or plugin. Cleanup, recovery, completion, and orchestration use durable workflow evidence: WU id, lane lock, session/lease evidence, lane branch, worktree path, done stamp, and audit records.

This matters when multiple agents or surfaces work in the same workspace:

• active/recent WU leases block destructive cleanup;
• missing active worktrees should be restored with pnpm wu:recover --id WU-XXX --action restore when the lane branch exists;
• stale delegation rows are reconciled against WU/stamp/execution evidence before they are treated as stuck work;
• client hooks and model labels are useful metadata, not authority.

Tool working-directory semantics

Some agent tools cannot set a per-call working directory. Relative paths then resolve against the agent runner’s process CWD, which may still be the main checkout. Launch agents from the claimed worktree, use the generated launch-wrapper.sh when delegating, and verify edits with git status in the worktree before finishing.

Bootstrap-safe commands

Agents often begin with command discovery, memory, orchestration, or setup checks in a clean WU worktree. Root LumenFlow package scripts should route through node tools/cli-entry.mjs <entry> instead of direct packages/@lumenflow/cli/dist/*.js paths. The wrapper can use an existing main checkout dist or build on demand, which keeps pnpm mem:create --help, pnpm orchestrate:monitor --help, pnpm lumenflow:commands, and pnpm lumenflow:setup-prereqs --help from failing before work starts.

Before dispatching local database or local model work, run:

pnpm lumenflow:setup-prereqs --json

The JSON report gives agents status values for Supabase CLI, Docker, Supabase local stack, Ollama binary, the OpenAI-compatible local API, and the configured Ollama model. It intentionally omits local service keys and token-shaped values, so agents should cite the status fields rather than paste raw supabase start, .envrc, or provider-token output.

Integration Options

LumenFlow provides four ways for AI agents to interact with the workflow:

Interface	Best For	Setup
File-based	Any AI that can read markdown	Point AI at AGENTS.md
CLI	Terminal-based agents, scripts	pnpm wu:claim, etc.
MCP	Programmatic access via MCP protocol	Setup Guide
Agent plugins	Discovery from Claude/Codex plugin surfaces	Planned — not yet shipped as of 5.4.0. When packaged: install the plugin, then run repo-level LumenFlow setup

The MCP server (@lumenflow/mcp) exposes workflow tools and resources over the Model Context Protocol, enabling AI assistants to interact with LumenFlow programmatically. See the MCP Reference for available tools.

Agent Plugins

Agent plugin distribution is being prepared as a future capability. Treat plugins as an on-ramp into LumenFlow, not as the runtime that enforces LumenFlow.

What the plugin can provide:

• Skills and first-run guidance that teach the agent how to enter the workflow
• Client-side hooks and MCP configuration where the vendor supports them
• Marketplace discovery for users who search Claude Code or Codex before they know about LumenFlow

What still requires repo-level setup:

• Work Unit state, lanes, gates, evidence, and shared memory
• Husky hooks, GitHub Actions, package aliases, and co-change gates
• The Software Delivery Pack runtime

Run npx lumenflow init in a new repository, or pnpm lumenflow:integrate --sync in an existing LumenFlow repository, when you want governed workflow state and enforcement. If both standalone projected skills and plugin skills are installed, use the surface-specific name: standalone skills use local names such as design-first, while Claude plugin skills use names such as /lumenflow:design-first.

Fast Feedback Hooks

Fast feedback is an opt-in hook projection for mid-turn check output. It helps an agent see scoped typecheck or lint failures shortly after a file edit, before the WU reaches wu:prep.

software_delivery:
  fast_feedback:
    enabled: true
    command: pnpm typecheck

If command is omitted, LumenFlow uses the project’s typecheck script when one exists in package.json; otherwise the hook silently no-ops. Choose a fast, scoped, or incremental command. Do not use this for a full cold test suite on every edit.

Fast feedback is not enforcement:

• Failures are returned through the client’s hook output/context channel.
• The hook exits successfully so edits are never blocked.
• LumenFlow does not auto-retry, launch fixer agents, or treat hook output as proof of completion.
• wu:prep and wu:done gates remain the authority for shipping.

Run pnpm lumenflow:integrate --client <client> after changing the setting.

| Client | Projection | | ------------ | ----------------------------------------------------------- | ------ | | Claude Code | .claude/settings.json PostToolUse on Write | Edit | | Codex CLI | .codex/hooks.json PostToolUse on Edit | Write | | Cursor | .cursor/hooks.json afterFileEdit | | Windsurf | .windsurf/hooks.json post_write_code with show_output | | Other client | No projection; WU gates still enforce completion |

AI as Teammate

LumenFlow is designed for AI agents to:

• Understand work context (WU specs)
• Execute autonomously (clear acceptance)
• Prove completion (gates + stamps)
• Recover context (memory layer)

Agent Onboarding

Provide agents with:

1. WU Spec – The work to be done
2. Acceptance Criteria – Definition of done
3. Code Paths – Where to work
4. Memory Context – What happened before

Prompt Template

## Context

You are working on WU-042 in the LumenFlow workflow.

## Work Unit

- ID: WU-042
- Title: Add email validation to login form
- Lane: UI
- Status: in_progress

## Acceptance Criteria

1. Email field validates on blur
2. Invalid emails show "Please enter a valid email"
3. Valid emails allow form submission
4. Unit test covers validation logic

## Code Paths

- src/components/LoginForm.tsx
- src/utils/validation.ts

## Instructions

1. Work in worktree: worktrees/ui-wu-042
2. Implement changes per acceptance
3. Run: pnpm wu:prep --id WU-042
4. From main: pnpm wu:done --id WU-042

Memory Integration

For long-running agent sessions:

# Agent starts session
pnpm mem:start --wu WU-042

# Agent signals progress
pnpm mem:signal "Validation logic complete" --wu WU-042

# Agent creates checkpoint (before pause/context limit)
pnpm mem:checkpoint --wu WU-042

# Agent resumes later
pnpm mem:ready --wu WU-042
# → Shows previous progress

Context Recovery

When an agent session ends and a new one begins:

# New agent runs
pnpm mem:ready --wu WU-042

# Output:
# WU-042 in progress
# Last signal: "Validation logic complete"
# Files touched: src/utils/validation.ts
# Next: Add unit tests

The agent can continue where the previous session left off.

Autonomous Execution

For trusted agents, enable autonomous mode:

# WU spec
autonomous: true
approval_required: false

The agent can:

• Claim and complete without human approval
• Make decisions within scope
• Log decisions for audit

Caution

Use autonomous mode only for well-scoped WUs with clear boundaries. Human oversight is still recommended for security-sensitive or customer-facing changes.

Safety Guardrails

LumenFlow provides defense-in-depth safety for AI agents through the kernel runtime, not just repository-level hooks.

Kernel-Level Enforcement

Every tool call passes through the kernel’s authorization gate before execution:

1. Scope intersection — The kernel computes workspace ∩ lane ∩ task ∩ tool permissions. An agent working in lane Framework: Core cannot write to apps/ even if it tries — the intersection is empty, so the call is denied.

2. Policy evaluation — Pack-declared policies use a deny-wins cascade. A deny at any layer (workspace, lane, pack, or task) is final and cannot be reversed. Gates, path restrictions, and approval requirements are all policies.

3. Evidence recording — Every tool call is recorded with content-addressed inputs, scope enforcement results, and policy decisions. Even denied calls produce evidence — the audit trail has no gaps.

4. Reserved path protection — Writes to .lumenflow/** are denied unconditionally. The kernel’s own state is tamper-proof.

Tip

These protections are kernel-enforced — they cannot be bypassed by calling tools directly. The agent never interacts with the filesystem without the kernel’s authorization gate.

Subprocess Isolation

Write operations and anything requiring OS-level isolation run in sandboxed subprocesses. On Linux, the kernel uses bwrap (bubblewrap) to create lightweight sandboxes that restrict filesystem access, network access, and system calls. The subprocess can only access paths within the computed scope intersection.

Repository-Level Safety

Additional protections work for all agents regardless of IDE or AI provider:

Git Safety Wrapper (scripts/safe-git):

# Blocks dangerous operations automatically
./scripts/safe-git worktree remove ...  # BLOCKED
./scripts/safe-git reset --hard         # BLOCKED
./scripts/safe-git clean -fd            # BLOCKED
./scripts/safe-git push --force         # BLOCKED

Husky Pre-Commit Hooks:

• Secret scanning (AWS/GitHub/OpenAI keys)
• Absolute path scanning (common home-dir absolute paths; prefer ~ or relative paths)
• Lockfile sync validation
• Worktree discipline enforcement

Escalation

Agents should escalate when:

• Acceptance criteria are unclear
• Security concerns arise
• Scope seems larger than WU

pnpm wu:block --id WU-042 --reason "Unclear: should validation be server-side too?"

Cloud Agent Branches

Cloud-hosted agents (like Prompt Studio, GitHub Actions, or custom automation) that create their own branches can bypass worktree requirements.

Configuration

Add patterns to your config to allow specific branch prefixes:

# workspace.yaml
git:
  mainBranch: main
  agentBranchPatterns:
    - 'agent/*' # Default: agent-created branches
    - 'claude/*' # Optional: Claude-specific branches
    - 'automation/*' # Optional: CI/CD automation

How It Works

When a branch matches an agentBranchPatterns glob:

• Worktree requirement bypassed – Agent can work in main checkout
• Git shim allows destructive commands – Agent manages its own isolation
• Write/Edit hooks allow file changes – No worktree check enforced

Caution

Protected branches (mainBranch and master) are never bypassed, even if they match a pattern. Lane branches (lane/*) also require worktrees regardless of patterns.

Headless Mode for CI/CD

For pipelines that don’t use branch patterns, enable guarded headless mode:

# Requires one guard to prevent accidental local use
export LUMENFLOW_HEADLESS=1
export CI=true  # or LUMENFLOW_ADMIN=1 or GITHUB_ACTIONS=true

This bypasses worktree checks for automation that manages its own isolation.

Detection Priority

The system evaluates in this order (first match wins):

1. Headless mode (if guarded) → bypass
2. Detached HEAD → protected (fail-closed)
3. Agent branch pattern match → bypass
4. Protected branch → protected
5. Lane branch → protected (use worktree)
6. Unknown branch → protected (fail-closed)

Note

The fail-closed design means unknown branches are blocked when worktrees exist. This prevents accidental work in the wrong location.

Multi-Agent Coordination

When multiple agents work in parallel:

Lane Isolation

Each agent works in a separate lane:

Agent A → Lane: UI → WU-100
Agent B → Lane: Core → WU-101
Agent C → Lane: Infra → WU-102

No conflicts, parallel progress.

Dependency Handling

If WUs depend on each other:

# WU-101
dependencies:
  - WU-100 # Agent B waits for Agent A

Agent B blocks until WU-100 is done.

Agent Types

Coding Agent

Implements code per WU spec:

• Writes code
• Writes tests
• Runs gates
• Completes WU

Review Agent

Reviews completed WUs:

• Checks code quality
• Validates against acceptance
• Suggests improvements

Discovery Agent

Explores and documents:

• Research spikes
• Architecture decisions
• Documentation updates

Best Practices

For Human-Agent Collaboration

1. Clear WU specs – Agents need explicit acceptance
2. Small WUs – Easier for agents to complete
3. Frequent checkpoints – Recover from context limits
4. Review agent work – Trust but verify

For Fully Autonomous Agents

1. Strict scope limits – Prevent runaway changes
2. Gate enforcement – Quality checks are non-negotiable
3. Audit trails – Log all decisions and actions
4. Kill switch – Ability to pause/stop agent work

Skills

LumenFlow supports agent skills — modular knowledge bundles that provide domain expertise and validation checklists. The canonical source lives in .lumenflow/skills/, and pnpm lumenflow:integrate --client <x> projects those skills into each vendor’s expected surface (for example .claude/skills/ or .agents/skills/).

Plugin-distributed skills use the client’s plugin surface instead of replacing the canonical source. For example, a standalone Claude skill may be invoked as design-first, while the Claude plugin surface uses /lumenflow:design-first. Codex plugin prompts should select the installed plugin or bundled skill through Codex’s @ plugin selection surface.

Available Skills

Skill	Purpose
wu-lifecycle	WU claim/block/done workflow automation
worktree-discipline	Prevent absolute path trap in worktrees
tdd-workflow	RED-GREEN-REFACTOR, test-driven development
lumenflow-gates	Gate troubleshooting (format/lint/typecheck)
library-first	Validate libraries exist before custom code
context-discipline	Search first, range-read by default
context-management	Session checkpoints, sub-agent spawning
bug-classification	P0-P3 triage, fix-in-place vs Bug WU
code-quality	SOLID/DRY patterns, TypeScript standards
multi-agent-coordination	Git branch locking for parallel WUs
orchestration	Agent dashboard, initiative execution
execution-memory	Session tracking, context recovery
initiative-management	Multi-phase INIT-XXX coordination
frontend-design	React/UI component patterns
ops-maintenance	Maintenance tasks, metrics, validation

Loading Skills

Skills are loaded automatically by wu:brief based on WU context, or manually:

# Claude Code
/skill wu-lifecycle
/skill tdd-workflow

# View canonical skills
ls .lumenflow/skills/

Skill Structure

Each skill has a SKILL.md with YAML frontmatter:

---
name: skill-name
description: One-line description for skill selection
version: 1.0.0
source: path/to/canonical/source.md
last_updated: YYYY-MM-DD
allowed-tools: Read, Bash, Grep
---

Configuration

Skills per lane can be configured in workspace.yaml:

agents:
  clients:
    claude-code:
      skills:
        instructions: 'Load skills based on WU context:'
        recommended:
          - wu-lifecycle
          - worktree-discipline
        byLane:
          'Framework: Core':
            - tdd-workflow
            - lumenflow-gates

Agents

The recommended framework roster is vendor-neutral. Client-specific overlays such as .claude/agents/, .codex/agents/, or other vendor rule surfaces may render these aliases differently, but the role names stay stable across clients:

Agent	Purpose
general-purpose	Standard WU implementation
lumenflow-pm	WU lifecycle, backlog management, coordination
test-engineer	TDD, coverage gaps, verification depth
code-reviewer	PR review, quality checks
bug-triage	Bug classification (P0-P3)
lumenflow-enforcer	WU validation and gates enforcement
initiative-architect	Initiative decomposition and execution design

Spawning Agents

Use wu:brief to generate Task tool invocations with proper context:

pnpm wu:brief --id WU-001 --client <client>

Next Steps

• Kernel Runtime — How every tool call is authorized and audited
• Scope Intersection — The 4-level permission model
• Policy Engine — Deny-wins rule evaluation
• Evidence Store — Immutable audit trail
• Memory Layer — Context persistence details
• CLI Reference — Agent-relevant commands