Existing Projects

Software Delivery Pack setup

This guide walks through adding the Software Delivery Pack to an existing project. The pack provides WUs, lanes, gates, and all CLI commands. The underlying kernel handles governance (scope, policy, evidence) automatically.

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

Path configuration is workspace-driven

Task and docs paths are resolved from workspace.yaml (software_delivery.directories.*). The default layout is docs/tasks/*. If you prefer arc42, run init with --docs-structure arc42 or set directory paths explicitly.

Prerequisites

Before starting:

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

Quick Overview

LumenFlow adds:

• workspace.yaml - Configuration file
• LUMENFLOW.md - Workflow entry point
• .lumenflow/ - State and constraints
• docs/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 lumenflow

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

   pnpm lumenflow \
     --framework nextjs \
     --main-branch main \
     --docs-structure simple

   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 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? There is no --client/--vendor flag any more — pnpm lumenflow always scaffolds the same universal surfaces (AGENTS.md, LUMENFLOW.md, .lumenflow/skills/, workspace.yaml) for every project, regardless of which AI tool you use. Point your tool at those files directly, or adapt them into your tool’s own config/rules/ instruction mechanism yourself — see AI Coding Assistant Integrations for how.

3. Review generated files

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

   • workspace.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/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.

   lumenflow init no longer creates any vendor-specific overlay files (no CLAUDE.md, .cursor/, .windsurf/, etc.) — the universal surfaces above are all that get scaffolded. Adapt them into your own AI tool’s native format yourself; see AI Coding Assistant Integrations.

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 workspace.yaml in your repo root:

   software_delivery:
     directories:
       wu_dir: docs/tasks/wu
       initiatives_dir: docs/tasks/initiatives
       backlog_path: docs/tasks/backlog.md
       status_path: docs/tasks/status.md
     lanes:
       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/tasks/backlog.md`
   2. Create WU: Create YAML in `docs/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](workspace.yaml)

3. Create directory structure

   mkdir -p docs/tasks/wu
   mkdir -p .lumenflow/state/packs/software-delivery/stamps

4. Create backlog.md

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

5. Create your first WU

   Create docs/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:
     - workspace.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/actions/lumenflow-gates@v4
        with:
          skip-on-no-wu: true # Only run if WU exists

Re-running init to backfill missing entries

Running lumenflow init on a repo that already has LumenFlow files is safe. For the .gitignore specifically, init checks each entry in REQUIRED_GITIGNORE_EXCLUSIONS against the existing file and appends only the missing ones under a # LumenFlow (auto-added) header. No existing entries are modified or duplicated.

This is useful after upgrading @lumenflow/cli when new ephemeral paths have been added to the exclusion list. For example, if your .gitignore is missing entries for .lumenflow/checkpoints/ or .lumenflow/locks/, re-running init will add them:

pnpm lumenflow

Ignore rules do not untrack files that are already in the index. Audit the local kernel tree first, then remove only the runtime paths you deliberately selected from the index. --cached preserves the local files:

# Include both root and nested workspace paths in this Git repository:
git ls-files -- '.lumenflow/kernel/**' ':(glob)**/.lumenflow/kernel/**'
# Review the output, then pass only those exact tracked files to:
git rm --cached -- <reviewed-file> [<reviewed-file>...]
git add .gitignore
git commit -m "fix: keep kernel runtime state local"

Repeat init or upgrade and this audit inside every independent nested Git repository; a parent repository’s ignore rules never apply across that boundary.

Treat .lumenflow/kernel/ as sensitive operational state. For a complete recoverable backup, stop and drain every runtime using the workspace, then capture the whole tree coherently. Never copy the active SQLite database alone: its WAL may contain committed pages and the surrounding task specs, migration state, and evidence are part of the recovery point. The -shm sidecar is transient and stale lock files are not restore payloads. SQLite’s Online Backup API or VACUUM INTO is suitable only for an explicitly database-only copy; it does not freeze the rest of the runtime tree.

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 of existing tickets to WU YAML

”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 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 wu:claim --id WU-123 --lane "Operations: Infrastructure"
pnpm wu:brief --id WU-123 --client <client>

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

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

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

# 6. Check results
ls .lumenflow/state/packs/software-delivery/stamps/WU-123.done  # Should exist

Next Steps

• Solo Developer Workflow - Simpler setup for individuals
• Team Workflow - Team-specific practices
• CLI Reference - Full command documentation