Existing Projects

Adding LumenFlow to an existing project takes about 15 minutes. This guide walks through the process without disrupting your current workflow.

Prerequisites

Before starting:

• Git repository (any platform)
• Node.js 22+ (for CLI)
• Understanding of Work Units and Gates

Quick Overview

LumenFlow adds:

• .lumenflow.config.yaml - Configuration file
• LUMENFLOW.md - Workflow entry point
• .lumenflow/ - State and constraints
• docs/04-operations/tasks/ - WU specs and backlog (optional)
• Git hooks for enforcement (optional)

It does not require:

• Changing your existing code structure
• Migrating existing tickets immediately
• Modifying CI/CD pipelines (optional enhancement)
• Team-wide adoption at once

Installation Methods

CLI (Recommended)

Full Setup with CLI

The CLI provides the fastest path to adoption.

1. Install the CLI

   pnpm
   bash pnpm add -D @lumenflow/cli
   npm
   bash npm install -D @lumenflow/cli

2. Initialize LumenFlow

   pnpm exec lumenflow

   Answer the prompts or use flags for non-interactive setup:

   pnpm exec lumenflow \
     --framework nextjs \
     --main-branch main

   Agent onboarding docs are included by default. Use --minimal to skip them.

   Adding to existing config files? Use --merge mode to safely insert LumenFlow configuration into your existing AGENTS.md or other files without overwriting your content:

   pnpm exec lumenflow --merge

   The merge mode uses bounded markers (<!-- LUMENFLOW:START --> and <!-- LUMENFLOW:END -->) to safely insert and update the LumenFlow block. Running --merge twice produces no changes on the second run (idempotent).

   Using a specific AI coding tool? Use the --client flag to generate client-specific overlay files:

   # Claude Code / Claude in IDE
   pnpm exec lumenflow --client claude
   
   # Cursor IDE
   pnpm exec lumenflow --client cursor
   
   # Windsurf IDE
   pnpm exec lumenflow --client windsurf
   
   # All clients
   pnpm exec lumenflow --client all

3. Review generated files

   The init command creates (agent onboarding docs are now included by default):

   • .lumenflow.config.yaml (your configuration) - LUMENFLOW.md (workflow entry point) - AGENTS.md (universal AI agent entry point) - .lumenflow/ - constraints.md (non-negotiable rules) - agents/ (AI agent guidance) - docs/04-operations/ - tasks/ - backlog.md - status.md - wu/ (WU spec directory) - _frameworks/lumenflow/agent/onboarding/ - quick-ref-commands.md (CLI command reference) - first-wu-mistakes.md (common pitfalls) - troubleshooting-wu-done.md (wu:done issues) - agent-safety-card.md (safety reference)

   Use --minimal to skip agent onboarding docs if you want a lighter setup.

   With --client flags, additional overlay files are created:

   Client Flag	Files Created
   --client claude	CLAUDE.md
   --client cursor	.cursor/rules/lumenflow.md
   --client windsurf	.windsurf/rules/lumenflow.md
   --client all	All of the above

4. Add scripts to package.json

   {
     "scripts": {
       "wu:create": "wu-create",
       "wu:claim": "wu-claim",
       "wu:prep": "wu-prep",
       "wu:done": "wu-done",
       "gates": "gates"
     }
   }

5. Git hooks (auto-scaffolded)

   lumenflow init automatically creates .husky/pre-commit (blocks main commits) and scripts/safe-git (blocks dangerous git operations). To also run gates on commit:

   # Optional: Add gates to pre-commit
   echo 'npx gates --quick' >> .husky/pre-commit

Manual Setup

Manual Setup (No CLI)

If you prefer not to use the CLI or are using a non-Node.js project.

1. Create configuration file

   Create .lumenflow.config.yaml in your repo root:

   version: '2.0'
   
   directories:
     wu_specs: docs/04-operations/tasks/wu
     backlog: docs/04-operations/tasks/backlog.md
     status: docs/04-operations/tasks/status.md
     stamps: .lumenflow/stamps
   
   lanes:
     enforcement:
       require_parent: true
       allow_custom: false
     definitions:
       - name: 'Framework: Core'
         wip_limit: 2
       - name: 'Experience: UI'
         wip_limit: 2
       - name: 'Operations: Infrastructure'
         wip_limit: 1
       - name: 'Content: Documentation'
         wip_limit: 1
   
   gates:
     execution:
       format: 'npm run format:check'
       lint: 'npm run lint'
       typecheck: 'npm run typecheck'
       test: 'npm test'
   
   git:
     main_branch: main

2. Create LUMENFLOW.md

   # LumenFlow Workflow Guide
   
   This project uses LumenFlow for AI-native development.
   
   ## Quick Start
   
   1. Review backlog: `docs/04-operations/tasks/backlog.md`
   2. Create WU: Create YAML in `docs/04-operations/tasks/wu/`
   3. Claim WU: Update status to `in_progress`
   4. Work: Implement per acceptance criteria
   5. Complete: Run `wu:prep` (gates), then `wu:done` and create the stamp
   
   ## Reference
   
   - [LumenFlow Documentation](https://lumenflow.dev)
   - [Configuration](.lumenflow.config.yaml)

3. Create directory structure

   mkdir -p docs/04-operations/tasks/wu
   mkdir -p .lumenflow/stamps

4. Create backlog.md

   # Backlog
   
   ## Ready
   
   ## In Progress
   
   ## Done

5. Create your first WU

   Create docs/04-operations/tasks/wu/WU-001.yaml:

   id: WU-001
   title: Initial LumenFlow setup
   lane: 'Operations: Infrastructure'
   type: chore
   status: done
   priority: P2
   description: |
     Set up LumenFlow workflow framework.
   acceptance:
     - Configuration file created
     - Directory structure established
   code_paths:
     - .lumenflow.config.yaml
     - LUMENFLOW.md

Mapping Existing Structure

Your Gates Are Already There

Most projects already have the tools LumenFlow gates run. Map them:

Gate	Your Existing Command	LumenFlow Config
Format	npm run prettier	gates.execution.format
Lint	npm run eslint	gates.execution.lint
Typecheck	npm run tsc	gates.execution.typecheck
Test	npm test	gates.execution.test

Example mapping:

gates:
  execution:
    format: 'npm run prettier -- --check'
    lint: 'npm run eslint'
    typecheck: 'npm run tsc --noEmit'
    test: 'npm test'

Your Branches Map to Lanes

If you have team branches or areas:

Current Branches	LumenFlow Lanes
feature/*, frontend-*	Experience: UI
api/*, backend-*	Framework: Core
infra/*, devops-*	Operations: Infrastructure
docs/*	Content: Documentation

Your PRs Map to WUs

Each pull request or ticket becomes a Work Unit:

PR/Ticket Field	WU Field
Title	title
Description	description
Labels	lane, type
Acceptance	acceptance
Assignee	assigned_to

Gradual Adoption Path

You don’t need to migrate everything at once.

Week 1: Shadow Mode

Run LumenFlow alongside existing workflow:

1. Install and configure
2. Create WUs for new work only
3. Keep using existing tickets for in-progress work
4. Run gates manually to test

Tip

Use --dry-run flags to test without committing changes while you learn the workflow.

Week 2-3: Parallel Operation

1. New work starts as WUs
2. Existing PRs complete normally
3. When a PR completes, optionally create a retroactive WU for history
4. Team familiarizes with commands

Week 4+: Full Adoption

1. All new work uses WUs
2. Close out ticket system (or keep for roadmap/epics)
3. Enable git hooks (auto-scaffolded by lumenflow init)

Coexistence Strategies

Keep External Roadmap

LumenFlow handles execution. Keep your roadmap tool:

Product Roadmap (Linear/Notion/Jira)
    ↓ Quarterly planning
Initiatives (INIT-001, INIT-002)
    ↓ Broken into
Work Units (WU-001, WU-002, ...)
    ↓ Executed via
LumenFlow

Link them:

# WU-042.yaml
id: WU-042
title: Add search autocomplete
initiative: INIT-008
external_refs:
  - 'LINEAR-1234'
  - 'JIRA-ABC-567'

Hybrid Team Adoption

Not everyone needs to adopt simultaneously:

Role	Adoption Level
AI Agents	Full LumenFlow (required)
Backend Team	Full LumenFlow (recommended)
Frontend Team	Gradual adoption
Product Manager	Continues using roadmap tool

Existing CI/CD

LumenFlow gates can run in CI without replacing your existing pipeline:

# .github/workflows/gates.yml
name: LumenFlow Gates
on: [pull_request]

jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hellmai/lumenflow-gates@v1
        with:
          skip-on-no-wu: true # Only run if WU exists

Common Concerns

”We have hundreds of open tickets”

You don’t need to migrate them. Options:

1. Ignore old tickets - Start fresh with WUs for new work
2. Migrate incrementally - Convert tickets as you work on them
3. Bulk migrate - Script conversion (see Migration Guide)

“Our team isn’t ready for trunk-based development”

LumenFlow supports gradual transition:

1. Start with worktrees (isolated, like feature branches)
2. Gates run in worktrees, merge when passing
3. This feels like PRs but with automated quality

”We need code review”

LumenFlow doesn’t eliminate review, it changes when:

• Gates replace mechanical review (format, lint, types, tests)
• Human review for security, architecture, judgment calls

# WU spec
requires_review: true
reviewers:
  - security@company.com

”Our tests are slow”

Use gate presets with test splitting:

gates:
  execution:
    test: 'npm test -- --shard=1/3' # Parallel shards
    test_timeout: 300000 # 5 minute timeout

Or run fast tests in gates, slow tests in CI.

Verification

After setup, verify everything works:

# 1. Create a test WU
pnpm exec wu-create \
  --title "Test LumenFlow setup" \
  --lane "Operations: Infrastructure" \
  --type documentation \
  --exposure documentation \
  --description "Verify LumenFlow CLI works in this repo" \
  --acceptance "WU can be claimed, prepped, and completed"

# 2. Claim it
# Use the generated ID from the output (example: WU-123)
pnpm exec wu-claim --id WU-123 --lane "Operations: Infrastructure"

# 3. Make a trivial change in worktree
cd worktrees/operations-infrastructure-wu-123
echo "# LumenFlow works" >> README.md

# 4. Run gates in worktree
pnpm exec wu-prep --id WU-123

# 5. Complete (from main checkout)
cd /path/to/main
pnpm exec wu-done --id WU-123

# 6. Check results
ls .lumenflow/stamps/WU-123.done  # Should exist

Next Steps

• Migration Guide - Migrate from existing tools
• Solo Developer Workflow - Simpler setup for individuals
• Team Workflow - Team-specific practices
• CLI Reference - Full command documentation